kopi-docka/docs/INSTALLATION.md

← Back to README

Installation

Think Simple Philosophy

Kopi-Docka expects a prepared system. We believe in user responsibility and system simplicity:

• ✅ You prepare your system (manually or with automation tools)
• ✅ We provide clear guidance on what's needed
• ❌ No automatic installations - keeps the codebase simple and maintainable
• ❌ No distro detection - works everywhere without complexity

Need automated setup? Use Server-Baukasten for automated system preparation.

---

System Requirements

Required Dependencies (MUST-HAVE)

These are non-negotiable - Kopi-Docka cannot function without them:

Dependency	Purpose	Installation
Docker	Container runtime for Kopi-Docka	docs.docker.com/engine/install
Kopia	Backup engine	kopia.io/docs/installation

Quick check:

docker --version
kopia --version

Optional Dependencies (SOFT)

These are needed for specific features and can be skipped with --skip-dependency-check:

Dependency	Needed For	Usually Pre-installed
tar	Disaster recovery bundles	✓ Most Linux distros
openssl	Encryption of recovery bundles	✓ Most Linux distros
rsync	Efficient volume restore	✓ Most Linux distros

Backend-Specific Dependencies

Checked automatically when you configure a backend:

Backend	Additional Tools Required
Tailscale	tailscale, ssh, ssh-keygen, ssh-copy-id
SFTP	ssh, ssh-keygen
Rclone	rclone

---

Installation Methods

Option 1: Automated Setup (Recommended)

Use Server-Baukasten for complete automated system preparation:

# Clone Server-Baukasten
git clone https://github.com/TZERO78/Server-Baukasten.git
cd Server-Baukasten

# Run setup (installs Docker, Kopia, SSH tools, etc.)
./setup.sh

# Then install Kopi-Docka
pipx install kopi-docka

✓ Benefits:

• Installs all required dependencies
• Configures system properly
• Handles distro-specific quirks
• Battle-tested automation

Option 2: Manual Installation

Step 1: Install Docker

Debian/Ubuntu:

# Official Docker installation
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Arch Linux:

sudo pacman -S docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Fedora/RHEL:

sudo dnf install docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Step 2: Install Kopia

Visit kopia.io/docs/installation for your platform.

Example (Debian/Ubuntu):

curl -s https://kopia.io/signing-key | sudo gpg --dearmor -o /usr/share/keyrings/kopia-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/kopia-keyring.gpg] https://packages.kopia.io/apt/ stable main" | sudo tee /etc/apt/sources.list.d/kopia.list
sudo apt update
sudo apt install kopia

Step 3: Install Optional Tools

For disaster recovery:

# Debian/Ubuntu
sudo apt install tar openssl

# Arch
sudo pacman -S tar openssl

# Fedora/RHEL
sudo dnf install tar openssl

For SSH-based backends (Tailscale, SFTP):

# Debian/Ubuntu
sudo apt install openssh-client

# Arch
sudo pacman -S openssh

# Fedora/RHEL
sudo dnf install openssh-clients

Step 4: Install Kopi-Docka

With pipx (Recommended - Isolated Environment):

# Install pipx if not present
sudo apt install pipx  # or: sudo pacman -S python-pipx
pipx ensurepath

# Install Kopi-Docka
pipx install kopi-docka

# Make available for sudo (pipx installs to ~/.local/bin)
sudo ln -s ~/.local/bin/kopi-docka /usr/local/bin/kopi-docka

# Verify
kopi-docka version
sudo kopi-docka version

Why the symlink? pipx installs to ~/.local/bin/ which is not in root's PATH. The symlink makes sudo kopi-docka work. Alternative: use full path sudo ~/.local/bin/kopi-docka or sudo -E kopi-docka.

With pip (System-wide):

pip install kopi-docka
# or
sudo pip install kopi-docka

From Source (Development):

git clone https://github.com/TZERO78/kopi-docka.git
cd kopi-docka

# Development mode
pip install -e .

# With dev dependencies
pip install -e ".[dev]"

---

Verify Installation

Run the system diagnostics command to check all dependencies:

kopi-docka doctor

Expected output:

✓ System Information
  OS: Linux
  Python: 3.12.3
  Kopi-Docka: 6.0.0

✓ Core Dependencies
  docker       [MUST_HAVE]   ✓ Installed   20.10.23   /usr/bin/docker
  kopia        [MUST_HAVE]   ✓ Installed   0.16.1     /usr/bin/kopia
  tar          [SOFT]        ✓ Installed   1.34       /usr/bin/tar
  openssl      [SOFT]        ✓ Installed   3.0.2      /usr/bin/openssl

---

Hard Gate vs Soft Gate

Kopi-Docka uses a two-tier dependency system:

Hard Gate (Non-Skippable)

Docker + Kopia are always required. Commands will refuse to run without them:

$ kopi-docka backup

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✗ Cannot proceed - required dependencies missing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Missing: docker

Kopi-Docka requires Docker and Kopia to function.

Installation:
  • Docker: https://docs.docker.com/engine/install/

Automated Setup:
  Use Server-Baukasten for automated system preparation:
  https://github.com/TZERO78/Server-Baukasten

Note: --skip-dependency-check does NOT apply to Docker/Kopia.

Soft Gate (Skippable)

tar, openssl are checked before disaster recovery but can be skipped:

$ kopi-docka disaster-recovery

✗ Missing optional dependencies: tar

Please install manually.

Or run with --skip-dependency-check (not recommended):
  kopi-docka disaster-recovery --skip-dependency-check

Using the skip flag:

$ kopi-docka disaster-recovery --skip-dependency-check

⚠️ Skipping dependency check for: tar
   Some features may not work correctly.

---

Updating Kopi-Docka

# pipx
pipx upgrade kopi-docka

# pip
pip install --upgrade kopi-docka

# Verify new version
kopi-docka version

---

Migration from v7.0.x to v7.1.0

No breaking changes — zero-effort upgrade

All new features in v7.1.0 use safe defaults. Existing configs run unmodified.

What changed (additive only):

New Config Key	Default	Effect without key
notifications.verbose	true	Failure notifications include stderr tail
notifications.preflight_check	true	Backend checked before container teardown
alerting.missed_backup.enabled	true	Missed-backup detection active
alerting.missed_backup.max_age_hours	26	26h threshold for daily backups

To opt out of any new behavior, add the key explicitly to your config:

{
  "notifications": {
    "verbose": false,
    "preflight_check": false
  },
  "alerting": {
    "missed_backup": { "enabled": false }
  }
}

After upgrading:

sudo kopi-docka doctor

Section 8 ("Backup Freshness") is new in doctor. It shows last-backup age per unit.

---

Migration from v5.4.x

Breaking Changes in v5.5.0

Removed features:

• ❌ kopi-docka install-deps command (no longer exists)
• ❌ Automatic dependency installation
• ❌ Distro detection logic
• ❌ Package manager integration

What you need to do:

1. Ensure Docker and Kopia are installed before upgrading
2. Run kopi-docka doctor after upgrading to verify dependencies
3. Use Server-Baukasten for automated system setup

If you relied on install-deps:

• Switch to manual installation (see above)
• Or use Server-Baukasten for automation

---

Troubleshooting

"command not found" when using sudo kopi-docka

Problem: After pipx installation, sudo kopi-docka fails with "command not found".

Cause: pipx installs to ~/.local/bin/ which is not in root's PATH.

Solutions:

Option 1: Create symlink (recommended)

sudo ln -s ~/.local/bin/kopi-docka /usr/local/bin/kopi-docka

Option 2: Use full path

sudo ~/.local/bin/kopi-docka backup

Option 3: Preserve PATH

sudo -E env "PATH=$PATH" kopi-docka backup

---

"Cannot proceed - required dependencies missing"

Problem: Docker or Kopia is not installed.

Solution:

# Check what's missing
kopi-docka doctor

# Install missing dependencies
# See "Manual Installation" section above

"Missing optional dependencies: tar, openssl"

Problem: tar or openssl is not available (rare on most Linux systems).

Solutions:

1. Install the missing tools (recommended)
2. Skip the check with --skip-dependency-check (not recommended)

Backend dependency errors

Problem: "Missing required tools for Tailscale backend: ssh, ssh-keygen"

Solution:

# Install OpenSSH client
sudo apt install openssh-client  # Debian/Ubuntu
sudo pacman -S openssh           # Arch
sudo dnf install openssh-clients # Fedora/RHEL

---

Next Steps

After installation:

1. Verify installation: kopi-docka doctor
2. Configure storage: kopi-docka setup
3. Create first backup: kopi-docka backup --dry-run
4. Read usage guide: USAGE.md

---

← Back to README