backupsidecar/README.md

BackupSidecar

BackupSidecar is a lightweight backup solution designed to run as a cron job in Kubernetes. It automates backups using Restic and supports both directory and PostgreSQL database backups. Optional notifications can be sent via Gotify to keep you informed of backup results.

Configuration

BackupSidecar is configured through environment variables. Below is a breakdown of the available settings.

General Settings

These variables apply to both directory and PostgreSQL backups.

• BACKUP_MODE (optional) - Defines the backup type (directory or postgres). Defaults to directory.
• RESTIC_PASSWORD (required) - The encryption password for Restic.
• RESTIC_REPOSITORY (required) - The URI of the Restic repository (e.g., rest:http://your-rest-server:8000/backup).
• RESTIC_REST_USERNAME (optional) - The username for REST server authentication.
• RESTIC_REST_PASSWORD (optional) - The password for REST server authentication.
• ENABLE_GOTIFY (optional) - Enable Gotify notifications. Set to true to enable, any other value or unset disables notifications. Defaults to true.
• GOTIFYHOST (required when ENABLE_GOTIFY=true) - The Gotify server URL.
• GOTIFYTOKEN (required when ENABLE_GOTIFY=true) - The API token for Gotify.
• GOTIFYTOPIC (required when ENABLE_GOTIFY=true) - The topic under which backup notifications will be sent.

Directory Backup

When running in directory mode, the following variable must be set:

• SOURCEDIR (required) - The path of the directory to be backed up.

PostgreSQL Backup

For postgres mode, the following database-related variables are required:

• PGHOST (required) - The hostname of the PostgreSQL server.
• PGDATABASE (required) - The name of the database to back up.
• PGUSER (required) - The PostgreSQL username.
• PGPORT (optional) - The port for PostgreSQL (defaults to 5432).
• PGPASSWORD (optional) - The password for authentication. Setting this prevents interactive prompts.
• PG_DUMP_ARGS (optional) - Additional flags for pg_dump.

Dependencies

Ensure the following commands are available in the container:

• restic
• curl
• jq
• pg_dump (only required for postgres mode)

Usage

Example Kubernetes CronJob manifest for running BackupSidecar as a cron job for directory backups in minimal configuration:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: backupsidecar-cron
  namespace: authentik
spec:
  schedule: "0 7 * * *"
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 5
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      backoffLimit: 3
      activeDeadlineSeconds: 300
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: backupsidecar
              image: backupsidecar:latest
              env:
                - name: RESTIC_REPOSITORY
                  value: "rest:http://rest-server:8000/backup"
                - name: RESTIC_PASSWORD
                  valueFrom:
                    secretKeyRef:
                      name: backupsidecar-secret
                      key: restic_password
                - name: BACKUP_MODE
                  value: "directory" # or "postgres"
                - name: SOURCEDIR
                  value: "/data/source"
                - name: ENABLE_GOTIFY
                  value: "true"
                - name: GOTIFYHOST
                  value: "http://gotify.example.com"
                - name: GOTIFYTOKEN
                  valueFrom:
                    secretKeyRef:
                      name: backupsidecar-secret
                      key: gotify_token
                - name: GOTIFYTOPIC
                  value: "Backup Notification"
              # (For PostgreSQL mode, add PGHOST, PGDATABASE, PGUSER, PGPORT, PGPASSWORD)
              volumeMounts:
                - name: source-data
                  mountPath: /data/source
          restartPolicy: OnFailure
          volumes:
            - name: source-data
              persistentVolumeClaim:
                claimName: source-data-pvc

Notifications

The script can send success or failure notifications via Gotify when enabled. To enable notifications, set ENABLE_GOTIFY=true and provide the required Gotify configuration variables (GOTIFYHOST, GOTIFYTOKEN, GOTIFYTOPIC). When notifications are disabled, backup status messages are still logged to the console.

Example success notification:

Backup successful. Snapshot 56ff6a909a44e01f67d2d88f9a76aa713d437809d7ed14a2361e28893f38befb: files new: 1, files changed: 0, data added: 1019 bytes in 0.277535184 sec

When Gotify is disabled, you'll see a single message at startup indicating notifications are disabled, followed by normal backup status messages:

2024-01-15T10:30:00 - Gotify notifications disabled. Backup status will be logged to console only.
2024-01-15T10:30:05 - Backup successful. Snapshot 56ff6a909a44e01f67d2d88f9a76aa713d437809d7ed14a2361e28893f38befb: files new: 1, files changed: 0, data added: 1019 bytes in 0.277535184 sec