kopi-docka 3.5.0

Robust cold backups for Docker environments using Kopia

Kopi-Docka

Robust Cold Backups for Docker Environments using Kopia

Kopi-Docka is a Python-based backup tool for Docker containers and their volumes. Features controlled downtime windows, encrypted snapshots, and automatic disaster recovery bundles.

---

What is Kopi-Docka?

Kopi-Docka = Kopia + Docker + Backup

A wrapper around Kopia, specifically designed for Docker environments:

• 📦 Stack-Aware - Backs up entire Docker Compose stacks as logical units
• 🔐 Encrypted - End-to-end encryption via Kopia (AES-256-GCM)
• 🌐 Multi-Backend - Local, S3, B2, Azure, GCS, SFTP, Tailscale
• 💾 Disaster Recovery - Encrypted emergency bundles with auto-reconnect
• 🔧 Pre/Post Hooks - Custom scripts for maintenance mode
• 📊 Systemd-Native - Production-ready daemon with sd_notify & watchdog
• 🚀 Restore Anywhere - Recovery on completely new hardware

See all features →

---

Quick Start

Installation

# Recommended: pipx (isolated environment)
pipx install kopi-docka

# Or: pip (system-wide)
pip install kopi-docka

Full installation guide →

Setup

# Interactive setup wizard
sudo kopi-docka setup

The wizard guides you through:

1. ✅ Dependency check (Kopia, Docker)
2. ✅ Backend selection (Local, S3, B2, Azure, GCS, SFTP, Tailscale)
3. ✅ Repository initialization
4. ✅ Connection test

Configuration guide →

First Backup

# System health check
sudo kopi-docka doctor

# List backup units (containers/stacks)
sudo kopi-docka admin snapshot list

# Test run (no changes)
sudo kopi-docka dry-run

# Full backup
sudo kopi-docka backup

# Create disaster recovery bundle (IMPORTANT!)
sudo kopi-docka disaster-recovery
# → Copy bundle to safe location: USB/cloud/safe!

Usage guide →

Automatic Backups

# Generate systemd units
sudo kopi-docka admin service write-units

# Enable daily backups (02:00 default)
sudo systemctl enable --now kopi-docka.timer

# Check status
sudo systemctl status kopi-docka.timer

Systemd integration →

---

Unique Features

1. Compose-Stack-Awareness

Automatically recognizes Docker Compose stacks and backs them up as atomic units with docker-compose.yml included.

kopi-docka admin snapshot list

Backup Units:
  - wordpress (Stack, 3 containers, 2 volumes)
  - nextcloud (Stack, 5 containers, 3 volumes)
  - gitlab (Stack, 4 containers, 4 volumes)

2. Disaster Recovery Bundles

Encrypted packages containing everything needed to reconnect to your repository on a new server. Time to recovery: 15-30 minutes instead of hours.

3. Tailscale Integration

Automatic peer discovery for P2P backups over your private network. Use your own hardware instead of cloud storage.

Available Backup Targets
┌─────────────┬─────────────────┐
│ Status      │ Hostname        │
├─────────────┼─────────────────┤
│ 🟢 Online  │ cloud-vps       │
│ 🟢 Online  │ home-nas        │
└────────────┴──────────────────┘

4. Systemd Integration

Production-ready daemon with sd_notify, watchdog monitoring, PID locking, and security hardening.

Read detailed feature documentation →

---

What's New in v3.5.0

• 🔧 Rclone Backend Improvements - Fixed PermissionError in config detection
• 💾 Enhanced DR Bundles - rclone.conf now included automatically in disaster recovery bundles
• 🐛 Kopia Flag Fix - Corrected flag generation: --rclone-config → --rclone-args='--config=...'
• 🛡️ Idempotent Recovery - rclone.conf restoration preserves existing configurations

Previous (v3.4.0):

• Simplified CLI with "The Big 6" commands
• Doctor Command for system health checks
• Organized admin subcommands

Previous (v3.3.0):

• Backup Scope Selection (minimal/standard/full)
• Docker Network Backup
• Pre/Post Backup Hooks
• Conflict Detection

See what's new →

---

Documentation

📚 Complete Documentation:

• Features - Unique features, what's new, why Kopi-Docka?
• Installation - System requirements, installation options
• Configuration - Wizards, config files, storage backends
• Usage - CLI commands, workflows, how it works
• Hooks - Pre/post backup hooks, examples
• Troubleshooting - Common issues, FAQ
• Development - Project structure, contributing

📁 Examples:

• examples/config.json - Sample configuration
• examples/docker-compose.yml - Example stack
• examples/hooks/ - Hook script examples
• examples/systemd/ - Systemd setup guide

---

CLI Commands

Kopi-Docka v3.4+ features a simplified CLI with "The Big 6" top-level commands and an admin subcommand for advanced operations.

Top-Level Commands ("The Big 6")

sudo kopi-docka setup              # Complete setup wizard
sudo kopi-docka backup             # Full backup (standard scope)
sudo kopi-docka restore            # Interactive restore wizard
sudo kopi-docka disaster-recovery  # Create DR bundle
sudo kopi-docka dry-run            # Simulate backup (preview)
sudo kopi-docka doctor             # System health check
kopi-docka version                 # Show version

Admin Commands (Advanced)

# Configuration
sudo kopi-docka admin config show      # Show config
sudo kopi-docka admin config new       # Create new config
sudo kopi-docka admin config edit      # Edit config

# Repository
sudo kopi-docka admin repo init        # Initialize repository
sudo kopi-docka admin repo status      # Repository info
sudo kopi-docka admin repo maintenance # Run maintenance

# Snapshots & Units
sudo kopi-docka admin snapshot list          # List backup units
sudo kopi-docka admin snapshot list --snapshots  # List all snapshots
sudo kopi-docka admin snapshot estimate-size # Estimate backup size

# System & Service
sudo kopi-docka admin system install-deps    # Install dependencies
sudo kopi-docka admin service write-units    # Generate systemd units
sudo kopi-docka admin service daemon         # Run as daemon

Complete CLI reference →

---

Storage Backends

Kopi-Docka supports 7 different backends:

1. Local Filesystem - Local disk or NAS mount
2. AWS S3 - Amazon S3 or compatible (Wasabi, MinIO)
3. Backblaze B2 - Affordable cloud storage (~$5/TB/month)
4. Azure Blob - Microsoft Azure storage
5. Google Cloud Storage - GCS
6. SFTP - Remote server via SSH
7. Tailscale - P2P over private network (no cloud costs!)

Backend configuration →

---

System Requirements

• OS: Linux (Debian, Ubuntu, Arch, Fedora, RHEL/CentOS)
• Python: 3.10 or newer
• Docker: Docker Engine 20.10+
• Kopia: 0.10+ (automatically checked)

Detailed requirements →

---

Feature Comparison

Feature	Kopi-Docka	docker-volume-backup	Duplicati	Restic
Docker-native	✅	✅	❌	❌
Compose-Stack-Aware	✅	❌	❌	❌
Network Backup	✅	❌	❌	❌
DR Bundles	✅	❌	❌	❌
Tailscale Integration	✅	❌	❌	❌
systemd-native	✅	❌	❌	❌
Pre/Post Hooks	✅	⚠️	❌	❌
Multi-Cloud	✅	✅	✅	✅

Full comparison →

---

Who Is It For?

• Homelab Operators - Multiple Docker hosts with offsite backups
• Self-Hosters - Docker services with professional backup strategy
• Small Businesses - Disaster recovery without enterprise costs
• Power Users - Full control over backup and restore processes

---

Credits & Acknowledgments

Author: Markus F. (TZERO78)

Links:

• PyPI: pypi.org/project/kopi-docka
• GitHub: github.com/TZERO78/kopi-docka

Powered by Kopia

Kopi-Docka wouldn't exist without Kopia!

Kopi-Docka is a wrapper that uses Kopia's powerful backup engine. Kopia provides:

• 🔐 End-to-end encryption (AES-256-GCM)
• 🗜️ Deduplication & compression
• ☁️ Multi-cloud support
• 📦 Incremental snapshots
• 🚀 High performance

Links:

• Kopia: https://kopia.io
• Kopia GitHub: https://github.com/kopia/kopia

Other Dependencies

• Docker - Container lifecycle management
• Typer - CLI framework
• psutil - System resource monitoring

Note: Kopi-Docka is an independent project with no official affiliation to Docker Inc. or the Kopia project.

---

License

MIT License - see LICENSE for details.

Copyright (c) 2025 Markus F. (TZERO78)

---

Support & Community

• 📦 PyPI: pypi.org/project/kopi-docka
• 📚 Documentation: Complete docs
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions

Love Kopi-Docka? Give us a ⭐ on GitHub!

---

Current Version: v3.5.0

View changelog | Contributing | Troubleshooting