borgitory 2.2.0__tar.gz

borgitory-2.2.0/.gitignore

@@ -0,0 +1,237 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Project specific ignores
+backup-sources/
+borg-repos/
+.claude/
+data/
+local-data/**
+*.db
+*.sqlite
+*.sqlite3
+
+# Docker
+.dockerignore
+
+# Local configuration
+.env.local
+.env.production
+
+# Runtime files
+*.pid
+*.log
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

borgitory-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matt LaPaglia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

borgitory-2.2.0/PKG-INFO

@@ -0,0 +1,441 @@
+Metadata-Version: 2.4
+Name: borgitory
+Version: 2.2.0
+Summary: A comprehensive web-based management interface for BorgBackup repositories with real-time monitoring, automated scheduling, and cloud synchronization capabilities.
+Project-URL: Homepage, https://github.com/mlapaglia/Borgitory
+Project-URL: Repository, https://github.com/mlapaglia/Borgitory
+Project-URL: Issues, https://github.com/mlapaglia/Borgitory/issues
+Author-email: mlapaglia <mlapaglia@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2025 Matt LaPaglia
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: archive-management,backup,borgbackup,cloud-sync,scheduling,web-interface
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: alembic>=1.16.5
+Requires-Dist: apscheduler>=3.10.4
+Requires-Dist: bcrypt<5.0.0,>=4.0.0
+Requires-Dist: cron-descriptor>=2.0.5
+Requires-Dist: cryptography>=45.0.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyfuse3>=3.4.0; sys_platform != 'win32'
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: python-multipart>=0.0.12
+Requires-Dist: sqlalchemy>=2.0.35
+Requires-Dist: sse-starlette>=2.1.3
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.25.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.11; extra == 'dev'
+Requires-Dist: sqlalchemy[mypy]>=2.0.35; extra == 'dev'
+Requires-Dist: types-aiofiles>=23.2.0.20240106; extra == 'dev'
+Requires-Dist: types-passlib>=1.7.7.20240327; extra == 'dev'
+Requires-Dist: types-python-dateutil>=2.8.19.20240106; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Borgitory
+
+[![codecov](https://codecov.io/gh/mlapaglia/Borgitory/graph/badge.svg?token=3XFFTWSKTB)](https://codecov.io/gh/mlapaglia/Borgitory)
+[![build](https://img.shields.io/github/actions/workflow/status/mlapaglia/borgitory/release.yml)](https://github.com/mlapaglia/Borgitory/actions/workflows/release.yml)
+[![sponsors](https://img.shields.io/github/sponsors/mlapaglia)](https://github.com/sponsors/mlapaglia)
+[![sponsors](https://img.shields.io/docker/pulls/mlapaglia/borgitory)](https://hub.docker.com/r/mlapaglia/borgitory)
+
+<img alt="borgitory logo" src="./assets/logo.png" width="400">
+
+A comprehensive web-based management interface for BorgBackup repositories with real-time monitoring, automated scheduling, and cloud synchronization capabilities.
+
+## Features
+
+### Core Functionality
+
+- **Repository Management**: Add, configure, and manage multiple Borg repositories
+- **Manual Backups**: Create backups on-demand with configurable compression and source paths
+- **Real-time Progress**: Monitor backup progress with live updates
+- **Archive Browser**: Interactive directory-based archive exploration with file downloads
+- **Job History**: Track all backup operations with detailed logs and expandable task views
+
+- **Automated Scheduling**: Set up cron-based backup schedules with integrated cleanup and notifications
+- **Archive Pruning**: Configure automated pruning policies with simple or advanced retention strategies
+- **Cloud Sync**: Synchronize repositories to S3-compatible storage using Rclone
+- **Push Notifications**: Pushover integration for job completion alerts
+- **User Authentication**: Secure username/password authentication
+- **Template System**: Modern Jinja2-based UI with reusable components
+- **Mobile Responsive**: HTMX + Alpine.js + Tailwind CSS interface
+
+## Quick Start
+
+### Prerequisites
+
+- **Docker Installation (Recommended)**: Docker with Docker Compose for containerized deployment
+- **PyPI Installation**: Python 3.11+ for direct installation from PyPI
+
+### Installation
+
+#### Option 1: PyPI Installation (New!)
+
+Install Borgitory directly from PyPI:
+
+```bash
+# Install stable release from PyPI
+pip install borgitory
+
+# Or install pre-release from TestPyPI (for testing new features)
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ borgitory
+
+# Start the server
+borgitory serve
+
+# Or run with custom settings
+borgitory serve --host 0.0.0.0 --port 8000
+```
+
+**PyPI Installation Requirements:**
+
+- Python 3.11 or higher
+- BorgBackup installed and available in PATH
+- Rclone (optional, for cloud sync features)
+
+**Note**: Pre-release versions are published to [TestPyPI](https://test.pypi.org/project/borgitory/) for testing before stable release.
+
+#### Option 2: Docker Installation
+
+1. **Pull and run the Docker image**
+
+   ```bash
+   # Using Docker directly
+   docker run -d \
+     -p 8000:8000 \
+     -v ./data:/app/data \
+     -v /path/to/backup/sources:/mnt/backup/sources:ro \
+     -v /path/to/borg/repos:/mnt/repos \
+     --cap-add SYS_ADMIN \
+     --device /dev/fuse \
+     --name borgitory \
+     mlapaglia/borgitory:latest
+   ```
+
+   **Or using Docker Compose** (create a `docker-compose.yml`):
+
+   ```yaml
+   version: '3.8'
+   services:
+     borgitory:
+       image: mlapaglia/borgitory:latest
+       ports:
+         - "8000:8000"
+       volumes:
+         - ./data:/app/data
+         - /path/to/backup/sources:/mnt/backup/sources:ro
+         - /path/to/borg/repos:/mnt/repos
+       cap_add:
+         - SYS_ADMIN
+       devices:
+         - /dev/fuse
+       restart: unless-stopped
+   ```
+
+   ```bash
+   docker-compose up -d
+   ```
+
+2. **Access the web interface**
+   - Open <http://localhost:8000> in your browser
+   - Create your first admin account on initial setup
+
+**Docker Hub**: Available at [mlapaglia/borgitory](https://hub.docker.com/r/mlapaglia/borgitory)
+
+### Docker Volumes
+
+```yaml
+volumes:
+  - ./data:/app/data # Persistent application data (required)
+  - /path/to/backup/sources:/mnt/backup/sources:ro # Source directories to backup (read-only)
+  - /path/to/borg/repos:/mnt/repos # Borg repository storage (read-write)
+  - /additional/source:/mnt/additional:ro # Additional source directories as needed
+  - /another/repo/location:/mnt/alt-repos # Additional repository locations as needed
+```
+
+**Volume Strategy:**
+
+- **Important**: All volumes must be mounted under `/mnt/` to be visible in the application
+- Mount as many volumes as necessary to access all your backup sources and repository locations
+- Source directories can be mounted read-only (`:ro`) for safety
+- Repository directories need read-write access for Borg operations
+- Each volume can be mapped to any convenient path under `/mnt/` inside the container
+- Supports distributed setups where repositories and sources are in different locations
+
+## Usage
+
+### 1. Repository Setup
+
+1. Navigate to the main dashboard
+2. Add a new repository:
+   - **Name**: Friendly identifier
+   - **Path**: Repository location (local or remote)
+   - **Passphrase**: Encryption password
+3. The system will validate the repository connection
+
+### 2. Creating Backups
+
+**Manual Backup:**
+
+1. Select repository from dropdown
+2. Configure source path and compression
+3. Click "Start Backup"
+4. Monitor progress in real-time
+
+**Scheduled Backup:**
+
+1. Go to Schedules section
+2. Create new schedule with cron expression
+3. Enable/disable schedules as needed
+
+### 3. Archive Pruning
+
+1. Create pruning policies:
+   - **Simple Strategy**: Keep archives within X days
+   - **Advanced Strategy**: Granular retention (daily/weekly/monthly/yearly)
+2. Configure options:
+   - Show detailed prune lists
+   - Display space savings statistics
+   - Force prune execution
+3. Attach policies to schedules or manual backups
+
+### 4. Archive Browsing
+
+**Exploring Archives:**
+
+1. Click "View Contents" on any archive to open the browser
+2. Navigate through directories by clicking folder names  
+3. View file details including size and modification dates
+4. Real-time directory exploration using FUSE-mounted archive filesystems
+
+**Downloading Files:**
+
+1. Click the download button (⬇) next to any file
+2. Files stream directly from the mounted archive without temporary storage
+3. Works efficiently with large files and slow connections
+4. Multiple downloads can run simultaneously
+5. Uses FUSE mounting for fast, direct file access
+
+**Requirements:**
+
+- Docker container must run with `--cap-add SYS_ADMIN` and `--device /dev/fuse`
+- Without FUSE support, archive browsing will be disabled
+
+### 5. Cloud Sync
+
+1. Configure S3 remote:
+   - Access Key ID and Secret
+2. Test connection
+3. Set up automatic sync after backups or manual sync
+
+### 6. Push Notifications
+
+1. Configure Pushover notifications:
+   - User Key and API Token
+2. Choose notification triggers:
+   - Success, failure, or both
+3. Attach to schedules for automated alerts
+
+## API Documentation
+
+The application provides a RESTful API with automatic OpenAPI documentation:
+
+- **Swagger UI**: <http://localhost:8000/docs>
+- **ReDoc**: <http://localhost:8000/redoc>
+
+## Deployment
+
+### Docker Compose (Recommended)
+
+```bash
+# Production deployment
+docker-compose -f docker-compose.yml up -d
+```
+
+### Manual Docker
+
+```bash
+# Build image
+docker build -t borgitory .
+
+# Run container with FUSE support for archive browsing
+docker run -d \
+  -p 8000:8000 \
+  -v ./data:/app/data \
+  -v /path/to/backup/sources:/mnt/backup/sources:ro \
+  -v /path/to/borg/repos:/mnt/repos \
+  --cap-add SYS_ADMIN \
+  --device /dev/fuse \
+  --name borgitory \
+  borgitory
+```
+
+**Required Docker Parameters:**
+
+- `--cap-add SYS_ADMIN`: Required for FUSE filesystem mounting to enable archive browsing
+- `--device /dev/fuse`: Provides access to FUSE device for archive file system mounting
+
+**FUSE Requirements:**
+
+- FUSE mounting enables the interactive archive browser feature
+- Allows real-time exploration of backup archives without extraction
+- Supports direct file downloads from mounted archive filesystems
+- Without FUSE support, archive browsing will be disabled
+
+## Project Dependencies
+
+This project uses modern Python packaging standards with all dependencies defined in `pyproject.toml`:
+
+> Install with `pip install -e .[dev]` to include development tools.
+
+## Architecture
+
+### Backend Stack
+
+- **FastAPI**: Modern Python web framework with automatic OpenAPI docs
+- **SQLite**: Lightweight database for configuration and job history
+- **APScheduler**: Advanced job scheduling and cron support
+- **Jinja2**: Powerful template engine for dynamic HTML generation
+- **Passlib**: Secure password hashing and verification
+- **Pushover**: Push notification service integration
+
+### Frontend Stack
+
+- **HTMX**: Dynamic HTML updates without JavaScript frameworks
+- **Alpine.js**: Lightweight JavaScript reactivity
+- **Tailwind CSS**: Utility-first styling with responsive design
+- **Server-Sent Events**: Real-time progress updates and live job monitoring
+
+### Job Management System
+
+- **Real-time Monitoring**: Live job output streaming with expandable task details
+- **Progress Tracking**: Detailed progress indicators for each job stage
+- **Job History**: Persistent storage of job results with searchable history
+- **Task Management**: Individual task tracking within jobs
+
+### Security Features
+
+- Username/password authentication with bcrypt hashing
+- Secure session management
+- Encrypted credential storage (Fernet)
+
+## Troubleshooting
+
+### Logs
+
+```bash
+# View application logs
+docker-compose logs -f borgitory
+
+# Check specific container logs
+docker logs <container-id>
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Run lint (`python lint.py all`)
+4. Run tests (`pytest`)
+5. Commit changes (`git commit -m 'Add amazing feature'`)
+6. Push to branch (`git push origin feature/amazing-feature`)
+7. Open Pull Request
+
+### Adding additional cloud destinations
+
+- Refer to [CLOUD_PROVIDERS.md](https://github.com/mlapaglia/borgitory/blob/main/CLOUD_PROVIDERS.md) for adding additional cloud destinations.
+
+### Development Setup
+
+1. **Set up Python virtual environment**
+
+   ```bash
+   # Create virtual environment
+   python -m venv .env_borg
+   
+   # Activate virtual environment
+   # On Windows:
+   .env_borg\Scripts\activate
+   # On macOS/Linux:
+   source .env_borg/bin/activate
+   ```
+
+2. **Install Python dependencies**
+
+   ```bash
+   # Install runtime dependencies only
+   pip install -e .
+   
+   # Install with development dependencies (testing, linting, etc.)
+   pip install -e .[dev]
+   
+   # Or install stable release from PyPI for testing
+   pip install borgitory
+   
+   # Or install pre-release from TestPyPI for testing new features
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ borgitory
+   ```
+
+   > **Note**: This project uses modern Python packaging with `pyproject.toml` following PEP 518 standards and is available on PyPI. All dependencies and project metadata are defined in a single configuration file.
+
+3. **Install Rclone** (for cloud sync)
+
+   ```bash
+   # On Ubuntu/Debian
+   curl https://rclone.org/install.sh | sudo bash
+   
+   # On macOS
+   brew install rclone
+   ```
+
+4. **Run development server**
+
+   ```bash
+   python run.py
+   ```
+
+5. **Run tests**
+
+   ```bash
+   pytest
+   ```