# Kopi-Docka
[](https://pypi.org/project/kopi-docka/)
[](https://pypi.org/project/kopi-docka/)
[](https://github.com/TZERO78/kopi-docka/blob/main/LICENSE)
[](https://github.com/TZERO78/kopi-docka/actions)
Cold backup solution for Docker environments using Kopia.
Kopi-Docka performs consistent backups of Docker containers by stopping them, creating snapshots of docker-compose files and volumes, then restarting services. Backups are encrypted and stored in Kopia repositories with configurable retention policies.
---
## Restore Process
### Interactive Restore Wizard
Start the restore wizard:
```bash
kopi-docka restore
```
The wizard guides you through these steps:
**1. Select Backup Session**
Lists available backup sessions grouped by time (5-minute tolerance):
```
📅 Available Backup Sessions:
1. 2025-01-15 02:00:45
Units: mysql-stack, nginx-stack (2 units, 8 volumes)
2. 2025-01-14 02:00:12
Units: mysql-stack, nginx-stack, redis (3 units, 10 volumes)
Select session (number or 'q' to quit): _
```
**2. Select Backup Unit**
If multiple units in session, choose which to restore:
```
📦 Units in this backup session:
1. mysql-stack (3 volumes) - 02:00:45
2. nginx-stack (2 volumes) - 02:00:48
Select unit to restore (number or 'q' to quit): _
```
**3. Confirm Restore**
Review what will be restored:
```
✅ Selected: mysql-stack from 2025-01-15 02:00:45
📝 This will guide you through restoring:
- Recipe/configuration files
- 3 volumes
Proceed with restore? (yes/no/q): _
```
**4. Recipe Restoration**
Automatically restores to temporary directory:
```
📂 Restoring recipes...
✓ docker-compose.yml
✓ mysql-db_inspect.json
✓ mysql-web_inspect.json
📁 Restored to: /tmp/kopia-restore-20250115-020045/recipes/mysql-stack/
```
**5. Volume Restoration**
For each volume, choose immediate or manual restore:
```
📦 Volume Restoration:
📁 Volume: mysql-data
📸 Snapshot: a3f5d892...
⚠️ Restore 'mysql-data' NOW? (yes/no/q):
```
**If you choose 'yes':**
- Stops affected containers
- Creates safety backup in `/tmp`
- Restores volume directly
- Restarts containers
**If you choose 'no':**
- Shows manual restore instructions
- Continues to next volume
**6. Service Restart**
After restore completes, start services:
```
cd /tmp/kopia-restore-20250115-020045/recipes/mysql-stack/
docker compose up -d
```
### Restore Options
**Restore specific snapshot:**
```bash
# List all snapshots
kopi-docka list --snapshots
# Restore uses interactive wizard
kopi-docka restore
```
**Restore to different server:**
```bash
# 1. Install Kopi-Docka on new server
pipx install kopi-docka
# 2. Connect to existing repository
kopi-docka init
# Configure same repository_path and password
# 3. Restore
kopi-docka restore
```
**Manual volume restore:**
If you declined automatic restore or need to restore later:
```bash
# Stop containers using the volume
docker ps -q --filter 'volume=mysql-data' | xargs docker stop
# Create safety backup
docker run --rm -v mysql-data:/source -v /tmp:/backup \
alpine tar czf /backup/mysql-data-backup.tar.gz -C /source .
# Restore from Kopia
kopia snapshot restore SNAPSHOT_ID /target/path
# Or use tar stream
kopia snapshot restore SNAPSHOT_ID --mode tar | \
docker run --rm -i -v mysql-data:/target alpine \
sh -c "rm -rf /target/* /target/.[!.]* 2>/dev/null || true; \
tar -xpf - --numeric-owner --xattrs --acls -C /target"
# Restart containers
docker start CONTAINER_ID
```
### Restore Safety Features
- **Automatic safety backups** - Creates `/tmp/volume-backup-*.tar.gz` before overwriting
- **Quit anytime** - Press 'q' at any prompt to cancel
- **Manual instructions** - Shows exact commands if you decline automatic restore
- **Secret redaction warnings** - Alerts if restored files contain `***REDACTED***`
- **Container management** - Stops/starts containers automatically during volume restore
---
## Features
- Cold backups for data consistency
- Docker Compose stack awareness
- AES-256 encryption via Kopia
- Multiple storage backends (S3, B2, Azure, GCS, SFTP, local)
- Disaster recovery bundles
- Systemd timer integration with journald logging
- Configurable retention policies
- Interactive restore wizard
- Automatic dependency installation
- Full Kopia CLI compatibility (use Kopia directly with Kopi-Docka's repository)
---
## Installation
```bash
pipx install kopi-docka
# Install system dependencies (Docker, Kopia, tar, openssl)
sudo kopi-docka install-deps
```
Alternative with pip:
```bash
pip install kopi-docka
sudo kopi-docka install-deps
```
### Verify Installation
```bash
kopi-docka --version
kopi-docka check
```
---
## Requirements
- Linux (Debian/Ubuntu recommended, also Arch/Fedora)
- Docker Engine 20.10+
- Kopia CLI 0.10+ (tested with 0.10-0.18)
- Python 3.10+
- tar, openssl (usually pre-installed)
Verify versions:
```bash
docker --version
kopia --version
python3 --version
```
### Automatic Dependency Installation
```bash
kopi-docka check # Show missing dependencies
sudo kopi-docka install-deps # Install automatically
sudo kopi-docka install-deps --dry-run # Preview changes
```
Supported distributions: Debian/Ubuntu (apt), RHEL/CentOS/Fedora (yum/dnf), Arch Linux (pacman + AUR).
---
## Quick Start
```bash
# 1. Install and verify
pipx install kopi-docka
sudo kopi-docka install-deps
# 2. Create configuration
kopi-docka new-config
# Edit ~/.config/kopi-docka/config.conf:
# - repository_path: backup destination
# - password: change default password
# 3. Initialize repository
kopi-docka init
kopi-docka change-password
# 4. Verify setup
kopi-docka list --units
kopi-docka dry-run
# 5. Create backup
kopi-docka backup
# 6. Create disaster recovery bundle
kopi-docka disaster-recovery
```
---
## Configuration
Config file locations (by precedence):
- `/etc/kopi-docka.conf` (system-wide)
- `~/.config/kopi-docka/config.conf` (user-specific)
Kopi-Docka uses a dedicated Kopia profile (`~/.config/kopia/repository-kopi-docka.config`) and does not interfere with existing Kopia configurations.
Example configuration:
```ini
[kopia]
repository_path = b2://bucket-name/kopia
password = secure-password
compression = zstd
encryption = AES256-GCM-HMAC-SHA256
[backup]
parallel_workers = 4
stop_timeout = 30
[retention]
daily = 7
weekly = 4
monthly = 12
yearly = 5
[logging]
level = INFO # DEBUG, INFO, WARNING, ERROR
file = /var/log/kopi-docka.log # Optional file logging
max_size_mb = 100 # Log rotation size
backup_count = 5 # Keep 5 rotated logs
```
### Storage Backends
**Backblaze B2:**
```bash
export B2_APPLICATION_KEY_ID="key-id"
export B2_APPLICATION_KEY="key-secret"
```
```ini
repository_path = b2://bucket-name/kopia
```
**AWS S3:**
```bash
export AWS_ACCESS_KEY_ID="key-id"
export AWS_SECRET_ACCESS_KEY="key-secret"
```
```ini
repository_path = s3://bucket-name/kopia
```
**Local filesystem:**
```ini
repository_path = /backup/kopia-repository
```
Additional backends: Azure Blob Storage, Google Cloud Storage, SFTP.
---
## Automated Backups
### Systemd Timer Setup
```bash
sudo kopi-docka write-units
sudo systemctl daemon-reload
sudo systemctl enable --now kopi-docka.timer
```
### Check Status
```bash
systemctl list-timers kopi-docka.timer
systemctl status kopi-docka.timer
journalctl -u kopi-docka -f
```
### Journald Integration
When running under systemd, Kopi-Docka automatically outputs structured logs to the systemd journal with searchable fields:
```bash
# View all Kopi-Docka logs
journalctl -u kopi-docka
# Follow logs in real-time
journalctl -u kopi-docka -f
# Filter by specific backup unit
journalctl -u kopi-docka UNIT=my-stack
# Show only errors
journalctl -u kopi-docka -p err
# Show logs from last backup run
journalctl -u kopi-docka --since "1 hour ago"
# Filter by operation
journalctl -u kopi-docka OPERATION=backup
# Show with metadata
journalctl -u kopi-docka -o json-pretty
```
**Structured fields available:**
- `UNIT` - Backup unit name
- `OPERATION` - backup, restore, etc.
- `DURATION` - Operation duration in seconds
- `STATUS` - SUCCESS, FAILED, PARTIAL
- `MODULE` - Python module name
- `LEVEL` - Log level
Enhanced journald support with `python3-systemd`:
```bash
sudo apt install python3-systemd # Debian/Ubuntu
# or
sudo kopi-docka install-deps # Installs automatically
```
### Custom Schedule
```bash
sudo systemctl edit kopi-docka.timer
```
```ini
[Timer]
OnCalendar=*-*-* 03:00:00 # Daily at 03:00
Persistent=true
```
---
## Disaster Recovery
Disaster recovery bundles contain repository connection info, encrypted credentials, configuration, and restore scripts.
### Create Bundle
```bash
kopi-docka disaster-recovery
```
Automatic bundle updates after each backup:
```ini
[backup]
update_recovery_bundle = true
recovery_bundle_path = /backup/recovery
recovery_bundle_retention = 3
```
### Restore from Bundle
On a new server:
```bash
# 1. Install Kopi-Docka
pipx install kopi-docka
# 2. Decrypt bundle
openssl enc -aes-256-cbc -d -pbkdf2 \
-in bundle.tar.gz.enc -out bundle.tar.gz
# 3. Extract and reconnect
tar -xzf bundle.tar.gz
cd kopi-docka-recovery-*/
sudo ./recover.sh
# 4. Restore data
kopi-docka restore
# 5. Start services
cd /tmp/kopia-restore-*/recipes/
docker compose up -d
```
---
## CLI Commands
### Backup & Restore
| Command | Description |
|---------|-------------|
| `list --units` | Show discovered backup units |
| `list --snapshots` | Show all backups in repository |
| `backup` | Create cold backup of selected units |
| `restore` | Interactive restore wizard (step-by-step) |
| `dry-run` | Simulate backup without changes |
### Repository
| Command | Description |
|---------|-------------|
| `init` | Initialize Kopia repository |
| `repo-status` | Check repository connection |
| `repo-maintenance` | Run Kopia maintenance |
| `change-password` | Change repository password |
### Configuration
| Command | Description |
|---------|-------------|
| `new-config` | Create config template |
| `show-config` | Display config (secrets masked) |
| `edit-config` | Open config in editor |
| `check` | Verify system dependencies |
| `install-deps` | Install missing dependencies |
### Disaster Recovery
| Command | Description |
|---------|-------------|
| `disaster-recovery` | Create encrypted DR bundle |
### Service
| Command | Description |
|---------|-------------|
| `write-units` | Generate systemd files |
| `daemon` | Run as systemd service |
---
## Kopia Profile Isolation
Kopi-Docka uses a separate Kopia profile and does not interfere with existing Kopia installations:
```bash
# Existing Kopia backups (default profile)
~/.config/kopia/repository.config
kopia snapshot create /home/user/documents
# Kopi-Docka (separate profile)
~/.config/kopia/repository-kopi-docka.config
kopi-docka backup
```
Both configurations operate independently with separate repositories, schedules, and retention policies.
---
## Direct Kopia Usage
Kopi-Docka is a wrapper around Kopia. You can use Kopia CLI directly with Kopi-Docka's repository by specifying the config file:
### Kopia Config File Location
```bash
# Kopi-Docka uses this config:
~/.config/kopia/repository-kopi-docka.config
# Your personal Kopia config (if any):
~/.config/kopia/repository.config
```
### Using Kopia with Kopi-Docka Repository
**Always specify the config file:**
```bash
# Set as alias for convenience
alias kopia-docka="kopia --config-file ~/.config/kopia/repository-kopi-docka.config"
# Or use full command
kopia --config-file ~/.config/kopia/repository-kopi-docka.config COMMAND
```
### Common Kopia Operations
**List snapshots:**
```bash
kopia --config-file ~/.config/kopia/repository-kopi-docka.config snapshot list
kopia --config-file ~/.config/kopia/repository-kopi-docka.config snapshot list --all
```
**Show snapshot details:**
```bash
kopia --config-file ~/.config/kopia/repository-kopi-docka.config snapshot show SNAPSHOT_ID
```
**Restore snapshot manually:**
```bash
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
snapshot restore SNAPSHOT_ID /restore/target/path
```
**Repository maintenance:**
```bash
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
maintenance run --full
```
**Check repository status:**
```bash
kopia --config-file ~/.config/kopia/repository-kopi-docka.config repository status
```
**Search snapshots by tag:**
```bash
# Find all backups for specific unit
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
snapshot list --tags=unit:mysql-stack
# Find all volume snapshots
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
snapshot list --tags=type:volume
```
**Mount repository as filesystem:**
```bash
mkdir /tmp/kopia-mount
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
mount all /tmp/kopia-mount
# Browse backups, then unmount:
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
unmount /tmp/kopia-mount
```
**Export snapshot to tar:**
```bash
kopia --config-file ~/.config/kopia/repository-kopi-docka.config \
snapshot restore SNAPSHOT_ID --mode tar > backup.tar
```
### Important Notes
- **Always use `--config-file`** when working with Kopi-Docka's repository
- Without `--config-file`, Kopia uses your default config (different repository!)
- Kopi-Docka tags snapshots with: `unit`, `type` (recipe/volume), `backup_id`, `timestamp`
- You can create custom snapshots in the same repository if needed
- Kopia policies are set per-unit (e.g., `recipes/mysql-stack`)
---
## Troubleshooting
### Missing Dependencies
```bash
kopi-docka check
sudo kopi-docka install-deps
sudo kopi-docka install-deps --dry-run # Preview only
```
After installation, logout and login for docker group membership to take effect.
### No Backup Units Found
Check Docker status and socket access:
```bash
docker ps
sudo usermod -aG docker $USER # Logout/login required
```
### Invalid Repository Password
Repository exists with different password:
```bash
# Update config with correct password, then:
kopi-docka init
```
To reinitialize (deletes existing backups):
```bash
sudo mv /backup/kopia-repository /backup/kopia-repository.backup
kopi-docka init
```
### Permission Issues
```bash
sudo mkdir -p /backup/kopia-repository
sudo chown $USER:$USER /backup/kopia-repository
```
### Restore Issues
**No restore points found:**
```bash
# Verify repository connection
kopi-docka repo-status
# List snapshots manually
kopi-docka list --snapshots
```
**Volume restore fails:**
```bash
# Check Docker is running
docker ps
# Ensure volume exists
docker volume ls | grep VOLUME_NAME
# Check available disk space
df -h
```
**Redacted secrets in restored files:**
Files containing `***REDACTED***` need manual intervention. Check `*_inspect.json` files in restored recipes and update environment variables manually before starting containers.
---
## Development
### Setup
```bash
git clone https://github.com/TZERO78/kopi-docka.git
cd kopi-docka
pip install -e ".[dev]"
```
### Tasks
```bash
make format # Format code (Black)
make check-style # Lint (flake8)
make test # Run tests
make test-unit # Unit tests only
make test-coverage # Coverage report
```
### Code Style
- Formatter: Black
- Linter: flake8
- Type hints: Encouraged
- Docstrings: Google style
---
## Contributing
Contributions are welcome. Please:
1. Fork the repository
2. Create a feature branch
3. Make changes and add tests
4. Run `make format` and `make test`
5. Submit a pull request
Report issues: [GitHub Issues](https://github.com/TZERO78/kopi-docka/issues)
---
## License
MIT License - see [LICENSE](LICENSE)
Copyright (c) 2025 Markus F. (TZERO78)
---
## Credits
- [Kopia](https://kopia.io/) - Backup engine with encryption and deduplication
- [Docker](https://www.docker.com/) - Container platform
- [Typer](https://typer.tiangolo.com/) - CLI framework
Kopi-Docka is an independent project with no official affiliation to Docker Inc. or the Kopia project.
---
## Links
- [PyPI Package](https://pypi.org/project/kopi-docka/)
- [GitHub Repository](https://github.com/TZERO78/kopi-docka)
- [Issue Tracker](https://github.com/TZERO78/kopi-docka/issues)
- [Discussions](https://github.com/TZERO78/kopi-docka/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "kopi-docka",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "docker, backup, kopia, containers, disaster-recovery",
"author": "Markus F. (TZERO78)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3a/eb/cf5289fb5e2dfdc809543b159d1e00f14f95f3932930f170ee66ae3047c4/kopi_docka-2.0.3.tar.gz",
"platform": null,
"description": "# Kopi-Docka\n\n[](https://pypi.org/project/kopi-docka/)\n[](https://pypi.org/project/kopi-docka/)\n[](https://github.com/TZERO78/kopi-docka/blob/main/LICENSE)\n[](https://github.com/TZERO78/kopi-docka/actions)\n\nCold backup solution for Docker environments using Kopia.\n\nKopi-Docka performs consistent backups of Docker containers by stopping them, creating snapshots of docker-compose files and volumes, then restarting services. Backups are encrypted and stored in Kopia repositories with configurable retention policies.\n\n---\n\n## Restore Process\n\n### Interactive Restore Wizard\n\nStart the restore wizard:\n\n```bash\nkopi-docka restore\n```\n\nThe wizard guides you through these steps:\n\n**1. Select Backup Session**\n\nLists available backup sessions grouped by time (5-minute tolerance):\n\n```\n\ud83d\udcc5 Available Backup Sessions:\n\n1. 2025-01-15 02:00:45\n Units: mysql-stack, nginx-stack (2 units, 8 volumes)\n\n2. 2025-01-14 02:00:12\n Units: mysql-stack, nginx-stack, redis (3 units, 10 volumes)\n\nSelect session (number or 'q' to quit): _\n```\n\n**2. Select Backup Unit**\n\nIf multiple units in session, choose which to restore:\n\n```\n\ud83d\udce6 Units in this backup session:\n\n1. mysql-stack (3 volumes) - 02:00:45\n2. nginx-stack (2 volumes) - 02:00:48\n\nSelect unit to restore (number or 'q' to quit): _\n```\n\n**3. Confirm Restore**\n\nReview what will be restored:\n\n```\n\u2705 Selected: mysql-stack from 2025-01-15 02:00:45\n\n\ud83d\udcdd This will guide you through restoring:\n - Recipe/configuration files\n - 3 volumes\n\nProceed with restore? (yes/no/q): _\n```\n\n**4. Recipe Restoration**\n\nAutomatically restores to temporary directory:\n\n```\n\ud83d\udcc2 Restoring recipes...\n \u2713 docker-compose.yml\n \u2713 mysql-db_inspect.json\n \u2713 mysql-web_inspect.json\n\n\ud83d\udcc1 Restored to: /tmp/kopia-restore-20250115-020045/recipes/mysql-stack/\n```\n\n**5. Volume Restoration**\n\nFor each volume, choose immediate or manual restore:\n\n```\n\ud83d\udce6 Volume Restoration:\n\n\ud83d\udcc1 Volume: mysql-data\n\ud83d\udcf8 Snapshot: a3f5d892...\n\n\u26a0\ufe0f Restore 'mysql-data' NOW? (yes/no/q):\n```\n\n**If you choose 'yes':**\n- Stops affected containers\n- Creates safety backup in `/tmp`\n- Restores volume directly\n- Restarts containers\n\n**If you choose 'no':**\n- Shows manual restore instructions\n- Continues to next volume\n\n**6. Service Restart**\n\nAfter restore completes, start services:\n\n```\ncd /tmp/kopia-restore-20250115-020045/recipes/mysql-stack/\ndocker compose up -d\n```\n\n### Restore Options\n\n**Restore specific snapshot:**\n\n```bash\n# List all snapshots\nkopi-docka list --snapshots\n\n# Restore uses interactive wizard\nkopi-docka restore\n```\n\n**Restore to different server:**\n\n```bash\n# 1. Install Kopi-Docka on new server\npipx install kopi-docka\n\n# 2. Connect to existing repository\nkopi-docka init\n# Configure same repository_path and password\n\n# 3. Restore\nkopi-docka restore\n```\n\n**Manual volume restore:**\n\nIf you declined automatic restore or need to restore later:\n\n```bash\n# Stop containers using the volume\ndocker ps -q --filter 'volume=mysql-data' | xargs docker stop\n\n# Create safety backup\ndocker run --rm -v mysql-data:/source -v /tmp:/backup \\\n alpine tar czf /backup/mysql-data-backup.tar.gz -C /source .\n\n# Restore from Kopia\nkopia snapshot restore SNAPSHOT_ID /target/path\n\n# Or use tar stream\nkopia snapshot restore SNAPSHOT_ID --mode tar | \\\n docker run --rm -i -v mysql-data:/target alpine \\\n sh -c \"rm -rf /target/* /target/.[!.]* 2>/dev/null || true; \\\n tar -xpf - --numeric-owner --xattrs --acls -C /target\"\n\n# Restart containers\ndocker start CONTAINER_ID\n```\n\n### Restore Safety Features\n\n- **Automatic safety backups** - Creates `/tmp/volume-backup-*.tar.gz` before overwriting\n- **Quit anytime** - Press 'q' at any prompt to cancel\n- **Manual instructions** - Shows exact commands if you decline automatic restore\n- **Secret redaction warnings** - Alerts if restored files contain `***REDACTED***`\n- **Container management** - Stops/starts containers automatically during volume restore\n\n---\n\n## Features\n\n- Cold backups for data consistency\n- Docker Compose stack awareness\n- AES-256 encryption via Kopia\n- Multiple storage backends (S3, B2, Azure, GCS, SFTP, local)\n- Disaster recovery bundles\n- Systemd timer integration with journald logging\n- Configurable retention policies\n- Interactive restore wizard\n- Automatic dependency installation\n- Full Kopia CLI compatibility (use Kopia directly with Kopi-Docka's repository)\n\n---\n\n## Installation\n\n```bash\npipx install kopi-docka\n\n# Install system dependencies (Docker, Kopia, tar, openssl)\nsudo kopi-docka install-deps\n```\n\nAlternative with pip:\n\n```bash\npip install kopi-docka\nsudo kopi-docka install-deps\n```\n\n### Verify Installation\n\n```bash\nkopi-docka --version\nkopi-docka check\n```\n\n---\n\n## Requirements\n\n- Linux (Debian/Ubuntu recommended, also Arch/Fedora)\n- Docker Engine 20.10+\n- Kopia CLI 0.10+ (tested with 0.10-0.18)\n- Python 3.10+\n- tar, openssl (usually pre-installed)\n\nVerify versions:\n\n```bash\ndocker --version\nkopia --version\npython3 --version\n```\n\n### Automatic Dependency Installation\n\n```bash\nkopi-docka check # Show missing dependencies\nsudo kopi-docka install-deps # Install automatically\nsudo kopi-docka install-deps --dry-run # Preview changes\n```\n\nSupported distributions: Debian/Ubuntu (apt), RHEL/CentOS/Fedora (yum/dnf), Arch Linux (pacman + AUR).\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install and verify\npipx install kopi-docka\nsudo kopi-docka install-deps\n\n# 2. Create configuration\nkopi-docka new-config\n# Edit ~/.config/kopi-docka/config.conf:\n# - repository_path: backup destination\n# - password: change default password\n\n# 3. Initialize repository\nkopi-docka init\nkopi-docka change-password\n\n# 4. Verify setup\nkopi-docka list --units\nkopi-docka dry-run\n\n# 5. Create backup\nkopi-docka backup\n\n# 6. Create disaster recovery bundle\nkopi-docka disaster-recovery\n```\n\n---\n\n## Configuration\n\nConfig file locations (by precedence):\n- `/etc/kopi-docka.conf` (system-wide)\n- `~/.config/kopi-docka/config.conf` (user-specific)\n\nKopi-Docka uses a dedicated Kopia profile (`~/.config/kopia/repository-kopi-docka.config`) and does not interfere with existing Kopia configurations.\n\nExample configuration:\n\n```ini\n[kopia]\nrepository_path = b2://bucket-name/kopia\npassword = secure-password\ncompression = zstd\nencryption = AES256-GCM-HMAC-SHA256\n\n[backup]\nparallel_workers = 4\nstop_timeout = 30\n\n[retention]\ndaily = 7\nweekly = 4\nmonthly = 12\nyearly = 5\n\n[logging]\nlevel = INFO # DEBUG, INFO, WARNING, ERROR\nfile = /var/log/kopi-docka.log # Optional file logging\nmax_size_mb = 100 # Log rotation size\nbackup_count = 5 # Keep 5 rotated logs\n```\n\n### Storage Backends\n\n**Backblaze B2:**\n```bash\nexport B2_APPLICATION_KEY_ID=\"key-id\"\nexport B2_APPLICATION_KEY=\"key-secret\"\n```\n```ini\nrepository_path = b2://bucket-name/kopia\n```\n\n**AWS S3:**\n```bash\nexport AWS_ACCESS_KEY_ID=\"key-id\"\nexport AWS_SECRET_ACCESS_KEY=\"key-secret\"\n```\n```ini\nrepository_path = s3://bucket-name/kopia\n```\n\n**Local filesystem:**\n```ini\nrepository_path = /backup/kopia-repository\n```\n\nAdditional backends: Azure Blob Storage, Google Cloud Storage, SFTP.\n\n---\n\n## Automated Backups\n\n### Systemd Timer Setup\n\n```bash\nsudo kopi-docka write-units\nsudo systemctl daemon-reload\nsudo systemctl enable --now kopi-docka.timer\n```\n\n### Check Status\n\n```bash\nsystemctl list-timers kopi-docka.timer\nsystemctl status kopi-docka.timer\njournalctl -u kopi-docka -f\n```\n\n### Journald Integration\n\nWhen running under systemd, Kopi-Docka automatically outputs structured logs to the systemd journal with searchable fields:\n\n```bash\n# View all Kopi-Docka logs\njournalctl -u kopi-docka\n\n# Follow logs in real-time\njournalctl -u kopi-docka -f\n\n# Filter by specific backup unit\njournalctl -u kopi-docka UNIT=my-stack\n\n# Show only errors\njournalctl -u kopi-docka -p err\n\n# Show logs from last backup run\njournalctl -u kopi-docka --since \"1 hour ago\"\n\n# Filter by operation\njournalctl -u kopi-docka OPERATION=backup\n\n# Show with metadata\njournalctl -u kopi-docka -o json-pretty\n```\n\n**Structured fields available:**\n- `UNIT` - Backup unit name\n- `OPERATION` - backup, restore, etc.\n- `DURATION` - Operation duration in seconds\n- `STATUS` - SUCCESS, FAILED, PARTIAL\n- `MODULE` - Python module name\n- `LEVEL` - Log level\n\nEnhanced journald support with `python3-systemd`:\n\n```bash\nsudo apt install python3-systemd # Debian/Ubuntu\n# or\nsudo kopi-docka install-deps # Installs automatically\n```\n\n### Custom Schedule\n\n```bash\nsudo systemctl edit kopi-docka.timer\n```\n\n```ini\n[Timer]\nOnCalendar=*-*-* 03:00:00 # Daily at 03:00\nPersistent=true\n```\n\n---\n\n## Disaster Recovery\n\nDisaster recovery bundles contain repository connection info, encrypted credentials, configuration, and restore scripts.\n\n### Create Bundle\n\n```bash\nkopi-docka disaster-recovery\n```\n\nAutomatic bundle updates after each backup:\n\n```ini\n[backup]\nupdate_recovery_bundle = true\nrecovery_bundle_path = /backup/recovery\nrecovery_bundle_retention = 3\n```\n\n### Restore from Bundle\n\nOn a new server:\n\n```bash\n# 1. Install Kopi-Docka\npipx install kopi-docka\n\n# 2. Decrypt bundle\nopenssl enc -aes-256-cbc -d -pbkdf2 \\\n -in bundle.tar.gz.enc -out bundle.tar.gz\n\n# 3. Extract and reconnect\ntar -xzf bundle.tar.gz\ncd kopi-docka-recovery-*/\nsudo ./recover.sh\n\n# 4. Restore data\nkopi-docka restore\n\n# 5. Start services\ncd /tmp/kopia-restore-*/recipes/\ndocker compose up -d\n```\n\n---\n\n## CLI Commands\n\n### Backup & Restore\n| Command | Description |\n|---------|-------------|\n| `list --units` | Show discovered backup units |\n| `list --snapshots` | Show all backups in repository |\n| `backup` | Create cold backup of selected units |\n| `restore` | Interactive restore wizard (step-by-step) |\n| `dry-run` | Simulate backup without changes |\n\n### Repository\n| Command | Description |\n|---------|-------------|\n| `init` | Initialize Kopia repository |\n| `repo-status` | Check repository connection |\n| `repo-maintenance` | Run Kopia maintenance |\n| `change-password` | Change repository password |\n\n### Configuration\n| Command | Description |\n|---------|-------------|\n| `new-config` | Create config template |\n| `show-config` | Display config (secrets masked) |\n| `edit-config` | Open config in editor |\n| `check` | Verify system dependencies |\n| `install-deps` | Install missing dependencies |\n\n### Disaster Recovery\n| Command | Description |\n|---------|-------------|\n| `disaster-recovery` | Create encrypted DR bundle |\n\n### Service\n| Command | Description |\n|---------|-------------|\n| `write-units` | Generate systemd files |\n| `daemon` | Run as systemd service |\n\n---\n\n## Kopia Profile Isolation\n\nKopi-Docka uses a separate Kopia profile and does not interfere with existing Kopia installations:\n\n```bash\n# Existing Kopia backups (default profile)\n~/.config/kopia/repository.config\nkopia snapshot create /home/user/documents\n\n# Kopi-Docka (separate profile)\n~/.config/kopia/repository-kopi-docka.config\nkopi-docka backup\n```\n\nBoth configurations operate independently with separate repositories, schedules, and retention policies.\n\n---\n\n## Direct Kopia Usage\n\nKopi-Docka is a wrapper around Kopia. You can use Kopia CLI directly with Kopi-Docka's repository by specifying the config file:\n\n### Kopia Config File Location\n\n```bash\n# Kopi-Docka uses this config:\n~/.config/kopia/repository-kopi-docka.config\n\n# Your personal Kopia config (if any):\n~/.config/kopia/repository.config\n```\n\n### Using Kopia with Kopi-Docka Repository\n\n**Always specify the config file:**\n\n```bash\n# Set as alias for convenience\nalias kopia-docka=\"kopia --config-file ~/.config/kopia/repository-kopi-docka.config\"\n\n# Or use full command\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config COMMAND\n```\n\n### Common Kopia Operations\n\n**List snapshots:**\n```bash\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config snapshot list\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config snapshot list --all\n```\n\n**Show snapshot details:**\n```bash\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config snapshot show SNAPSHOT_ID\n```\n\n**Restore snapshot manually:**\n```bash\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n snapshot restore SNAPSHOT_ID /restore/target/path\n```\n\n**Repository maintenance:**\n```bash\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n maintenance run --full\n```\n\n**Check repository status:**\n```bash\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config repository status\n```\n\n**Search snapshots by tag:**\n```bash\n# Find all backups for specific unit\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n snapshot list --tags=unit:mysql-stack\n\n# Find all volume snapshots\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n snapshot list --tags=type:volume\n```\n\n**Mount repository as filesystem:**\n```bash\nmkdir /tmp/kopia-mount\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n mount all /tmp/kopia-mount\n# Browse backups, then unmount:\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n unmount /tmp/kopia-mount\n```\n\n**Export snapshot to tar:**\n```bash\nkopia --config-file ~/.config/kopia/repository-kopi-docka.config \\\n snapshot restore SNAPSHOT_ID --mode tar > backup.tar\n```\n\n### Important Notes\n\n- **Always use `--config-file`** when working with Kopi-Docka's repository\n- Without `--config-file`, Kopia uses your default config (different repository!)\n- Kopi-Docka tags snapshots with: `unit`, `type` (recipe/volume), `backup_id`, `timestamp`\n- You can create custom snapshots in the same repository if needed\n- Kopia policies are set per-unit (e.g., `recipes/mysql-stack`)\n\n---\n\n## Troubleshooting\n\n### Missing Dependencies\n\n```bash\nkopi-docka check\nsudo kopi-docka install-deps\nsudo kopi-docka install-deps --dry-run # Preview only\n```\n\nAfter installation, logout and login for docker group membership to take effect.\n\n### No Backup Units Found\n\nCheck Docker status and socket access:\n\n```bash\ndocker ps\nsudo usermod -aG docker $USER # Logout/login required\n```\n\n### Invalid Repository Password\n\nRepository exists with different password:\n\n```bash\n# Update config with correct password, then:\nkopi-docka init\n```\n\nTo reinitialize (deletes existing backups):\n\n```bash\nsudo mv /backup/kopia-repository /backup/kopia-repository.backup\nkopi-docka init\n```\n\n### Permission Issues\n\n```bash\nsudo mkdir -p /backup/kopia-repository\nsudo chown $USER:$USER /backup/kopia-repository\n```\n\n### Restore Issues\n\n**No restore points found:**\n\n```bash\n# Verify repository connection\nkopi-docka repo-status\n\n# List snapshots manually\nkopi-docka list --snapshots\n```\n\n**Volume restore fails:**\n\n```bash\n# Check Docker is running\ndocker ps\n\n# Ensure volume exists\ndocker volume ls | grep VOLUME_NAME\n\n# Check available disk space\ndf -h\n```\n\n**Redacted secrets in restored files:**\n\nFiles containing `***REDACTED***` need manual intervention. Check `*_inspect.json` files in restored recipes and update environment variables manually before starting containers.\n\n---\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/TZERO78/kopi-docka.git\ncd kopi-docka\npip install -e \".[dev]\"\n```\n\n### Tasks\n\n```bash\nmake format # Format code (Black)\nmake check-style # Lint (flake8)\nmake test # Run tests\nmake test-unit # Unit tests only\nmake test-coverage # Coverage report\n```\n\n### Code Style\n\n- Formatter: Black\n- Linter: flake8\n- Type hints: Encouraged\n- Docstrings: Google style\n\n---\n\n## Contributing\n\nContributions are welcome. Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes and add tests\n4. Run `make format` and `make test`\n5. Submit a pull request\n\nReport issues: [GitHub Issues](https://github.com/TZERO78/kopi-docka/issues)\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\nCopyright (c) 2025 Markus F. (TZERO78)\n\n---\n\n## Credits\n\n- [Kopia](https://kopia.io/) - Backup engine with encryption and deduplication\n- [Docker](https://www.docker.com/) - Container platform\n- [Typer](https://typer.tiangolo.com/) - CLI framework\n\nKopi-Docka is an independent project with no official affiliation to Docker Inc. or the Kopia project.\n\n---\n\n## Links\n\n- [PyPI Package](https://pypi.org/project/kopi-docka/)\n- [GitHub Repository](https://github.com/TZERO78/kopi-docka)\n- [Issue Tracker](https://github.com/TZERO78/kopi-docka/issues)\n- [Discussions](https://github.com/TZERO78/kopi-docka/discussions)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Robust cold backups for Docker environments using Kopia",
"version": "2.0.3",
"project_urls": {
"Documentation": "https://github.com/TZERO78/kopi-docka#readme",
"Homepage": "https://github.com/TZERO78/kopi-docka",
"Issues": "https://github.com/TZERO78/kopi-docka/issues",
"Repository": "https://github.com/TZERO78/kopi-docka"
},
"split_keywords": [
"docker",
" backup",
" kopia",
" containers",
" disaster-recovery"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "179f83dfa89d2cee7964ff6c4e01cdb2c6f878c1c176a281b42b3b043bf5679a",
"md5": "7821cdbaa2b88bc46e991e10052460b7",
"sha256": "f2411acf97934f0001b4e5b0655579e2bf77c7e7d1e22f50d044dc70fe68cca9"
},
"downloads": -1,
"filename": "kopi_docka-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7821cdbaa2b88bc46e991e10052460b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 95654,
"upload_time": "2025-10-12T14:21:06",
"upload_time_iso_8601": "2025-10-12T14:21:06.390644Z",
"url": "https://files.pythonhosted.org/packages/17/9f/83dfa89d2cee7964ff6c4e01cdb2c6f878c1c176a281b42b3b043bf5679a/kopi_docka-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3aebcf5289fb5e2dfdc809543b159d1e00f14f95f3932930f170ee66ae3047c4",
"md5": "3472d86c1be24253e281c5f287d9a7c9",
"sha256": "819e7a6a3ebf028e3be578ee52eab697b9aceae0edde4bb81d5975c11d7db4a2"
},
"downloads": -1,
"filename": "kopi_docka-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "3472d86c1be24253e281c5f287d9a7c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 83735,
"upload_time": "2025-10-12T14:21:07",
"upload_time_iso_8601": "2025-10-12T14:21:07.904043Z",
"url": "https://files.pythonhosted.org/packages/3a/eb/cf5289fb5e2dfdc809543b159d1e00f14f95f3932930f170ee66ae3047c4/kopi_docka-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 14:21:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TZERO78",
"github_project": "kopi-docka#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "psutil",
"specs": [
[
">=",
"5.9.0"
]
]
}
],
"lcname": "kopi-docka"
}
JSON
