Skip to content

dsc backup

Create, list, download, restore, and set up off-site (S3) backups.

dsc backup health

dsc backup health [<discourse>] [--tags <tag1,tag2,...>] [--max-age <days>] [--format text|json|yaml|csv]

Checks actual S3 objects rather than Discourse's backup catalogue. With no <discourse>, checks every configured forum; use --tags to select a fleet subset. Every row reports the latest S3 backup archive, its age, its size, total bucket size, and total object count. Forums using local backups are reported as NOT_S3.

The default --max-age 2 marks a forum STALE when its latest archive is over two whole days old. MISSING, STALE, MISCONFIGURED, INACCESSIBLE, or UNKNOWN rows make the command exit non-zero after printing all selected rows, making it suitable for monitoring.

# Check every configured forum
dsc backup health

# Investigate one forum with a one-day freshness threshold
dsc backup health myforum --max-age 1

# Export a production fleet report for automation
dsc backup health --tags production --format json

Requires the aws CLI and its normal ambient credential chain. The existing single-bucket backup IAM policy already grants the required s3:ListBucket permission. This command is read-only: it never creates backups, changes settings, or deletes objects.

dsc backup create

dsc backup create <discourse>

Triggers a backup on the specified Discourse. The backup is created server-side; it is not downloaded locally.

dsc backup list

dsc backup list <discourse> [--format text|markdown|markdown-table|json|yaml|csv|urls] [--verbose]

Lists all backups on the specified Discourse. Supports the same formats as dsc list. -v/--verbose includes additional fields where supported.

dsc backup pull

dsc backup pull <discourse> <backup-filename> [<local-path>]

Downloads a backup archive to the local filesystem. <backup-filename> is the name shown by dsc backup list. If <local-path> is omitted, the file is saved in the current directory with the same name.

dsc backup pull myforum discourse-2026-04-17-230000.tar.gz
dsc backup pull myforum discourse-2026-04-17-230000.tar.gz ./backups/

dsc backup push

dsc backup push <discourse> <backup-path>

Restores the specified backup (alias: dsc backup restore). <backup-path> is the backup filename as shown by dsc backup list.

Restoration is destructive and irreversible. Use --dry-run (or -n) to preview the operation before committing:

dsc --dry-run backup push myforum discourse-2026-04-17-230000.tar.gz

dsc backup setup-s3

dsc backup setup-s3 <discourse> [--region <r>] [--bucket <name>] [--no-test]

Provisions off-site backups on Amazon S3 in one command, replacing the per-forum AWS-console runbook: it creates a private bucket, a dedicated single-bucket IAM user + least-privilege policy, mints an access key, and points Discourse's S3 backup settings at it - then (unless --no-test) triggers a backup and confirms it lands in the bucket.

Defaults derive from the forum's config name:

  • bucket <name>-discourse-backups, policy s3-single-bucket-<name>-discourse-backups, user <name>-discourse-backup-user
  • region eu-west-2 (override with --region); bucket override with --bucket

Requirements & safety:

  • The aws CLI must be installed and configured with a profile that has IAM + S3 admin rights. Those provisioning credentials are used only by aws and are never stored by dsc. The minted least-privilege key is written straight into the Discourse setting (not into dsc.toml) and is never printed.
  • This creates real AWS resources and writes production settings. Always preview with -n / --dry-run first - it prints the resolved names, the full IAM policy JSON, the exact aws commands, and the settings diff, and touches nothing.
# 1) Review the complete plan (creates nothing)
dsc backup setup-s3 -n myforum

# 2) Provision for real (eu-west-2 by default)
dsc backup setup-s3 myforum --region eu-west-1

Phase 1 covers the create-everything flow. --reuse-user (idempotent re-runs / key rotation), --use-iam-profile (EC2 instance role, no static keys), and --all/--tags (fleet-wide) are planned - see spec/commands/backup-s3-setup.md.