Skip to content

Backups

NGX Ops backs up the Nginx configuration: sites/, conf/, snippets/, streams/, ssl/ and the Let's Encrypt certificates (certs/live/). A backup can be made on demand from the Backups page, by a scheduled task, or automatically before a configuration change and before a deployment.

Destinations

Mode Local ZIP Git push S3
Local only ✓
Git only ✓
Local + Git ✓ ✓
S3 only ✓
Local + Git + S3 ✓ ✓ ✓

Local ZIPs are rotated automatically: BACKUP_KEEP sets the number kept (20 by default).

The Git push uses the repository configured for Git deployment, in the branch dedicated to backups (backup by default), with a timestamped tag.

S3 destination

It is configured in Configuration → Backups (S3, automatic targets), backup.yml file, without restart. It works with AWS, MinIO, Scaleway, OVH and Ceph. Signing is built in, with no dependency. HTTPS is mandatory, unless s3_allow_insecure: true (private network or test).

Key Role
s3_enable Enables the destination
s3_endpoint, s3_region, s3_bucket Service, region and bucket
s3_prefix Bucket folder (ngx-ops/ by default)
s3_path_style true for MinIO, Ceph and most S3-compatible services; false for AWS in virtual-host mode
s3_keep Backups kept in the bucket, per family (30; 0 disables rotation)
s3_timeout_s Request timeout (60)

Credentials: preferably set BACKUP_S3_ACCESS_KEY and BACKUP_S3_SECRET_KEY in the container environment; they win over the file. The minimum rights are s3:PutObject, s3:ListBucket and s3:DeleteObject on the prefix.

Dedicated prefix

Remote rotation deletes old .zip and *_ngxops.* files in the prefix. Use a folder reserved for NGX Ops backups.

The S3 destination card of the Backups page lists the bucket content and tests the connection.

Restoring from S3

NGX Ops does not restore from S3: download the archive with your S3 tools.

NGX Ops configuration files

s3_include_ngxops: true also sends a <date>_<label>_ngxops.tar.gz archive of the config/*.yml files. Secrets (tokens, keys) are excluded by default.

s3_include_secrets: true includes them, but requires a passphrase (S3_BACKUP_PASSPHRASE or the BACKUP_PASSPHRASE fallback): the archive is then encrypted in the .ngxb format.

Passphrases

One passphrase per feature, so as not to mix services deployed separately:

Variable Used for
HUB_BACKUP_PASSPHRASE Backups sent to the Hub
S3_BACKUP_PASSPHRASE Encrypted S3 archives
BACKUP_PASSPHRASE Common fallback when the specific variable is absent

There is no crossover: the Hub passphrase is never used for S3, nor the reverse.

Keep passphrases outside NGX Ops

An encrypted archive whose passphrase is lost is unrecoverable.

Open an encrypted archive

A .ngxb archive (NGXB1 format, AES-256-GCM) is decrypted with the dashboard's tools/ngxb-decrypt.js tool (Node 16 or later, no dependency):

HUB_BACKUP_PASSPHRASE='my passphrase' node ngxb-decrypt.js backup.ngxb output.tar.gz --extract ./folder

The passphrase is read from HUB_BACKUP_PASSPHRASE, S3_BACKUP_PASSPHRASE or BACKUP_PASSPHRASE, or from standard input: never as an argument, so it does not appear in ps or the shell history. A wrong passphrase or a tampered archive causes an error and nothing is written. For Hub archives, the Open button does this in the browser.

Automatic backup

Without any of the auto_local, auto_git and auto_s3 keys in backup.yml, the historical behavior applies: local ZIP, plus Git during a Git deployment. As soon as one of these keys is present, they apply everywhere, and those that are absent default to: local true, Git false, S3 false.

Choose a single destination type (S3 only, for example) to avoid storing three copies at each change.

Restoration

With Git configured

As long as Git is configured, restoring a local backup is refused, and the button disappears: the repository is the source of truth. To go back, use a git revert followed by a redeployment.