nself backup

Create encrypted, incremental backups of your nSelf Postgres database and Docker volumes — then restore them locally or from a remote store.

Quick start

# Create a full backup right now
nself backup create

# List all available backups
nself backup list

# Restore the most recent backup
nself backup restore latest

# Set up automatic nightly backups to S3
nself backup schedule --cron "0 2 * * *" --remote s3://my-bucket/nself

Synopsis

nself backup <SUBCOMMAND> [FLAGS] [ARGS]

Description

nself backup provides a complete data-protection layer for self-hosted nSelf deployments. All backups are encrypted at rest using an AES-256 key managed via nself backup init-key. Backups include:

• A full Postgres logical dump (via pg_dump) compressed with zstd
• Named Docker volumes for MinIO, Redis, MeiliSearch, and Functions
• The current .env + nginx/conf.d/ configuration snapshot

Backups are stored locally at ~/.nself/backups/ by default and can be mirrored to any S3-compatible store, SFTP target, or Hetzner Object Storage bucket using the --remote flag.

Use nself backup schedule to register a cron-based job that runs unattended. Use nself backup stream to pipe a live backup to stdout — useful for integrating with external backup orchestrators.

Subcommands

nself backup create

Create a new backup. Stops no services — uses Postgres MVCC consistency + volume snapshots.

nself backup create
# Backup ID: bkp_20260101T020000Z
# Postgres:  done (423 MB → 87 MB compressed)
# Volumes:   done (minio 1.2 GB → 310 MB)
# Encrypted: yes (key: ~/.nself/backup.key)

nself backup create --remote s3://my-bucket/nself
nself backup create --tag before-migration

nself backup list

List all local (and optionally remote) backups with ID, timestamp, size, and tags.

nself backup list
# ID                       DATE          SIZE    TAG
# bkp_20260101T020000Z     2026-01-01    397 MB  —
# bkp_20251231T020000Z     2025-12-31    391 MB  before-migration

nself backup list --remote s3://my-bucket/nself
nself backup list --json

nself backup restore

Restore a backup by ID or use latest for the most recent one.

nself backup restore latest
nself backup restore bkp_20251231T020000Z
nself backup restore latest --no-volumes   # DB only
nself backup restore latest --dry-run      # preview without applying

nself backup restore-remote

Pull a backup from a remote store and restore it directly without storing it locally first.

nself backup restore-remote s3://my-bucket/nself/bkp_20251231T020000Z
nself backup restore-remote hetzner://my-bucket/nself latest

nself backup verify

Verify a backup's integrity by checking the encrypted archive checksum and decryption.

nself backup verify latest
# bkp_20260101T020000Z: OK (checksum verified, decryption ok)

nself backup verify bkp_20251231T020000Z

nself backup prune

Delete old backups according to a retention policy. Keeps the most recent N backups and any backup created within the last D days.

nself backup prune --keep 7
nself backup prune --keep 30 --older-than 90d
nself backup prune --dry-run

nself backup config

Show or edit the backup configuration (local path, default remote, compression, retention).

nself backup config
nself backup config --set remote=s3://my-bucket/nself
nself backup config --set retention=30

nself backup status

Show the last backup time, next scheduled run, and remote sync state.

nself backup status
# Last backup:  2026-01-01T02:00:00Z (14h ago)
# Next backup:  2026-01-02T02:00:00Z (in 10h)
# Remote sync:  s3://my-bucket/nself (up to date)
# Schedule:     0 2 * * * (nightly at 02:00 UTC)

nself backup init-key

Generate a new AES-256 backup encryption key and save it to ~/.nself/backup.key. Run this once during initial setup or when rotating keys.

nself backup init-key
# Key written to: ~/.nself/backup.key
# Store this key securely — backups cannot be restored without it

nself backup stream

Pipe a live, encrypted backup archive to stdout. Useful for piping into external storage tools or S3 utilities directly.

nself backup stream | aws s3 cp - s3://my-bucket/nself/$(date +%Y%m%dT%H%M%SZ).tar.zst
nself backup stream > /mnt/nas/nself-backup.tar.zst

nself backup resume

Resume an interrupted backup transfer to a remote store.

nself backup resume bkp_20260101T020000Z
nself backup resume latest

nself backup schedule

Register or update the cron-based automatic backup schedule. Writes a launchd plist (macOS) or systemd timer (Linux) that runs nself backup createunattended.

nself backup schedule --cron "0 2 * * *"
nself backup schedule --cron "0 2 * * *" --remote s3://my-bucket/nself
nself backup schedule --disable
nself backup schedule --status

Examples

Full nightly backup to Hetzner Object Storage

nself backup init-key
nself backup schedule --cron "0 2 * * *" --remote hetzner://my-bucket/nself

Pre-migration snapshot with tag

nself backup create --tag pre-v110-migration
# Then run migrations...
nself migrate up
# If something goes wrong:
nself backup restore pre-v110-migration

Verify and prune on a schedule

nself backup verify latest && nself backup prune --keep 14 --dry-run
# Review dry-run output, then:
nself backup prune --keep 14

Pipe to an external tool

nself backup stream | rclone rcat remote:nself/$(date +%Y%m%d).tar.zst

Environment variables

• NSELF_BACKUP_DIR — local backup storage path (default: ~/.nself/backups)
• NSELF_BACKUP_KEY_PATH — path to the encryption key (default: ~/.nself/backup.key)
• NSELF_BACKUP_REMOTE — default remote store URL
• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY — credentials for S3-compatible stores
• HETZNER_OBJECT_STORAGE_KEY — key for Hetzner Object Storage remotes

Exit codes

• 0 — success
• 1 — backup or restore failed (see stderr for details)
• 2 — invalid arguments or backup key not found
• 3 — remote store unreachable or authentication failed

Related

• nself db — database migrations and direct Hasura management
• nself pitr — point-in-time recovery using WAL streaming
• nself dr — disaster recovery runbook and failover
• nself health — service health checks