Metadata-Version: 2.4
Name: kopi-docka
Version: 4.0.0
Summary: Robust cold backups for Docker environments using Kopia
Author: Markus F. (TZERO78)
License: MIT
Project-URL: Homepage, https://github.com/TZERO78/kopi-docka
Project-URL: Documentation, https://github.com/TZERO78/kopi-docka#readme
Project-URL: Repository, https://github.com/TZERO78/kopi-docka
Project-URL: Issues, https://github.com/TZERO78/kopi-docka/issues
Keywords: docker,backup,kopia,containers,disaster-recovery
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Archiving :: Backup
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: rich-click>=1.7.0
Provides-Extra: systemd
Requires-Dist: systemd-python>=234; extra == "systemd"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: license-file

# Kopi-Docka

> **Robust Cold Backup 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.

[![PyPI](https://img.shields.io/pypi/v/kopi-docka)](https://pypi.org/project/kopi-docka/)
[![Python Version](https://img.shields.io/pypi/pyversions/kopi-docka)](https://pypi.org/project/kopi-docka/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/kopi-docka)](https://pypi.org/project/kopi-docka/)

---

## What is Kopi-Docka?

**Kopi-Docka = Kopia + Docker + Backup**

A wrapper around [Kopia](https://kopia.io), 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-Storage** - 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 →](docs/FEATURES.md)**

---

## Quick Start

### Installation

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

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

**[Full installation guide →](docs/INSTALLATION.md)**

### Setup

```bash
# Interactive setup wizard
sudo kopi-docka setup
```

The wizard guides you through:
1. ✅ Dependency check (Kopia, Docker)
2. ✅ Repository storage selection (Local, S3, B2, Azure, GCS, SFTP, Tailscale)
3. ✅ Repository initialization
4. ✅ Connection test

**[Configuration guide →](docs/CONFIGURATION.md)**

### First Backup

```bash
# 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 →](docs/USAGE.md)**

### Automatic Backups

```bash
# 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

# Or use the interactive management wizard
sudo kopi-docka admin service manage
```

**[Systemd integration →](docs/FEATURES.md#4-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.

```bash
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 →](docs/FEATURES.md)**

---

## What's New in v4.0.0

- **🎨 Complete UI Consistency Refactoring** - Modern, beautiful CLI experience
  - All 11 command files modernized with Rich (Panels, Tables, Colors)
  - Consistent color scheme across all commands (green=success, red=error, yellow=warning, cyan=info)
  - Replaced all `typer.echo()` with Rich Console output
  - Beautiful styled tables for data presentation

- **📚 rich-click Integration** - Beautiful `--help` output
  - Styled command help with syntax highlighting
  - Organized option groups
  - Markdown support in docstrings

- **🔧 New UI Components** - 11 new helper functions in `ui_utils.py`
  - `print_panel()`, `print_menu()`, `print_step()`, `print_divider()`
  - `print_success_panel()`, `print_error_panel()`, `print_warning_panel()`, `print_info_panel()`
  - `print_next_steps()`, `get_menu_choice()`, `confirm_action()`, `create_status_table()`

- **🐛 Bug Fixes**
  - Fixed `log_manager.configure()` -> `log_manager.setup()` method name
  - Fixed missing imports in `ui_utils.py` (Progress, SpinnerColumn, TextColumn)

**Breaking Changes:** None (UI only, API unchanged)

**[See what's new →](docs/FEATURES.md#whats-new-in-v400)**

---

## Documentation

📚 **Complete Documentation:**

- **[Features](docs/FEATURES.md)** - Unique features, what's new, why Kopi-Docka?
- **[Installation](docs/INSTALLATION.md)** - System requirements, installation options
- **[Configuration](docs/CONFIGURATION.md)** - Wizards, config files, storage backends
- **[Usage](docs/USAGE.md)** - CLI commands, workflows, how it works
- **[Hooks](docs/HOOKS.md)** - Pre/post backup hooks, examples
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues, FAQ
- **[Development](docs/DEVELOPMENT.md)** - Project structure, contributing

📁 **Examples:**

- **[examples/config.json](examples/config.json)** - Sample configuration
- **[examples/docker-compose.yml](examples/docker-compose.yml)** - Example stack
- **[examples/hooks/](examples/hooks/)** - Hook script examples
- **[examples/systemd/](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")
```bash
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)
```bash
# 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 →](docs/USAGE.md#cli-commands-reference)**

---

## Repository Storage Types

Kopi-Docka supports 7 different repository storage types:

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!)

**[Repository storage configuration →](docs/CONFIGURATION.md#storage-backends)**

---

## 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 →](docs/INSTALLATION.md#system-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 →](docs/FEATURES.md#why-kopi-docka)**

---

## 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](https://pypi.org/project/kopi-docka/)
- GitHub: [github.com/TZERO78/kopi-docka](https://github.com/TZERO78/kopi-docka)

### Powered by Kopia

**Kopi-Docka wouldn't exist without [Kopia](https://kopia.io)!**

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](https://www.docker.com/)** - Container lifecycle management
- **[Typer](https://typer.tiangolo.com/)** - CLI framework
- **[psutil](https://github.com/giampaolo/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](LICENSE) for details.

Copyright (c) 2025 Markus F. (TZERO78)

---

## Support & Community

- 📦 **PyPI:** [pypi.org/project/kopi-docka](https://pypi.org/project/kopi-docka/)
- 📚 **Documentation:** [Complete docs](docs/)
- 🐛 **Bug Reports:** [GitHub Issues](https://github.com/TZERO78/kopi-docka/issues)
- 💬 **Discussions:** [GitHub Discussions](https://github.com/TZERO78/kopi-docka/discussions)

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

---

**Current Version:** v4.0.0

**[View changelog](docs/FEATURES.md#whats-new-in-v400)** | **[Contributing](docs/DEVELOPMENT.md#contributing)** | **[Troubleshooting](docs/TROUBLESHOOTING.md)**
