kopi-docka 3.3.1

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

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

# 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 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 list --units

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        │ Disk Free   │ Latency  │
├──────────┼─────────────────┼─────────────┼──────────┤
│ 🟢 Online│ cloud-vps      │ 450.2GB     │ 23ms     │
│ 🟢 Online│ home-nas       │ 2.8TB       │ 45ms     │
└──────────┴─────────────────┴─────────────┴──────────┘

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.3.0

• 🎯 Backup Scope Selection - minimal/standard/full scopes
• 🌐 Docker Network Backup - Complete IPAM configuration
• 🔧 Pre/Post Backup Hooks - Custom scripts for maintenance mode
• ⚠️ Conflict Detection - Interactive restore with conflict resolution

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

Setup & Configuration

sudo kopi-docka setup              # Master setup wizard
sudo kopi-docka new-config         # Config wizard only
sudo kopi-docka status             # Backend status (disk, connectivity)

Backup & Restore

sudo kopi-docka backup             # Full backup (standard scope)
sudo kopi-docka backup --scope minimal    # Volumes only
sudo kopi-docka backup --scope full       # Complete system
sudo kopi-docka restore            # Interactive restore wizard
sudo kopi-docka disaster-recovery  # Create DR bundle

Repository & Automation

sudo kopi-docka repo-status        # Repository info
sudo kopi-docka write-units        # Generate systemd units
sudo kopi-docka daemon             # Run as systemd 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.3.0

View changelog | Contributing | Troubleshooting