Quick Start & Reference

⚡  Quick Start

Get your first backup running in under 10 minutes.

1. Install

# Extract the archive received after contract signing
cd backup-framework
pip install -r requirements.txt

2. Configure

Copy the example environment file and fill in your credentials:

cp .env.example .env
# Edit .env with your S3 and MongoDB credentials

3. Register a bucket

Register your S3 bucket credentials once. The name is a local alias you choose.

python3 -m backup --register-bucket \
  --name my-bucket \
  --bucket prod-backups \
  --access-key <ACCESS_KEY> \
  --secret-key <SECRET_KEY> \
  --region us-east-1

For a non-AWS endpoint (MinIO, Cloudflare R2, Wasabi…) add --endpoint https://your.endpoint.

4. Register a job

Register a named job that binds a directory to a bucket.

python3 -m backup --register \
  --name daily-backup \
  --dir /path/to/your/data \
  --bucket my-bucket

5. Run your first backup

python3 -m backup --run --job daily-backup

6. Verify

# Check what was backed up
python3 -m backup status --job daily-backup

# Run a full audit (3 checks)
python3 -m backup audit --job daily-backup

📋  Requirements

⚙  Configuration

All configuration is via environment variables (or a .env file). No credentials are ever hardcoded.

Fernet credential encryption

S3 credentials are never stored in plaintext. Generate a key once and store it securely (or pull it from your secrets provider):

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Key rotation is supported via MultiFernet — see the full setup guide for the rotation procedure.

🖱  Deployment

Docker Compose (recommended for production)

# From the project directory received after contract signing
cp .env.example .env  # fill in credentials
docker compose up -d
# Web dashboard at https://localhost
# HTTP automatically redirects to HTTPS

systemd timer

[Unit]
Description=Arkhivio daily backup

[Service]
Type=oneshot
EnvironmentFile=/etc/arkhivio/.env
ExecStart=/usr/bin/python3 -m backup scan upload audit

[Install]
WantedBy=multi-user.target

Cron

# /etc/cron.d/arkhivio  — daily at 02:00
0 2 * * * backup-user /usr/bin/python3 -m backup scan upload audit --job daily

📄  Command Reference

Common flags

📁  Multiple Directories

A single job can back up multiple directories. All paths are tracked under one job, use one set of metrics, and upload in parallel.

python3 -m backup scan upload \
  --job full-server-backup \
  --dir /etc /var/www /home/deploy /opt/app

Global exclude patterns apply across all directories. Existing single-directory jobs require no changes — fully backward compatible.

⚖  Kubernetes

Pod names are ephemeral and change on every restart. Use --host to set a stable identity so all runs for a workload are grouped correctly in MongoDB and S3:

python3 -m backup scan upload audit \
  --job k8s-backup \
  --host my-deployment \
  --dir /data

🔔  Alerting

Because all events are JSON, any log aggregator can generate alerts by filtering on event field values. No special agent or plugin required.

Critical alerts (page immediately)

Warning alerts

Grafana Loki example rule

- alert: ArkhivioUploadError
  expr: |
    count_over_time(
      {app="arkhivio"} | json | event="upload_error"
      [5m]) > 0
  for: 0m
  labels:
    severity: critical
  annotations:
    summary: Arkhivio upload failure detected

Notification channels

Route alerts to: Slack, Microsoft Teams, PagerDuty, OpsGenie, email, or SMS — using your existing alerting pipeline.

📊  Log Integration

Set LOG_FILE=/var/log/arkhivio/backup.log to write to a rotating file (50 MB per file, 10 files retained) in addition to stdout. Both handlers emit identical newline-delimited JSON.

Supported log destinations

📝  Event Reference

Key events emitted by the framework (all include ts, event, level, job, host):