Configuration

Understand the files inside an instance and the small set of values an operator may change.

Instance files

stage-data/
  config.json       # settings, paths, and the saved port
  secrets.json      # generated database passwords; keep private
  state.json        # lifecycle and last-backup state
  data/             # PostgreSQL cluster and log
  backups/          # local dump, manifest, and checksum files

The directory and private files are created with restrictive permissions. Do not commit them or copy secrets.json into a public location.

Minimal configuration

init writes a configuration like this. The port is an example; the real value is chosen automatically.

{
  "schemaVersion": 1,
  "postgresMajor": 17,
  "database": "staging",
  "appRole": "stage_app",
  "adminRole": "stage_admin",
  "port": 55432,
  "originAddress": "127.0.0.1",
  "postgres": {
    "dataDirectory": "./data",
    "tls": {
      "certFile": "/etc/stage-pg/postgres.crt",
      "keyFile": "/etc/stage-pg/postgres.key",
    },
  },
  "cloudflareWorkers": {
    "originAddress": "127.0.0.1",
  },
  "tailscaleAdmins": {
    "mode": "serve-tcp",
  },
  "backup": {
    "intervalMinutes": 360,
    "directory": "./backups",
    "keepLocal": 7,
  },
}

Relative paths are relative to the instance folder. originAddress stays on loopback so the database is not directly exposed on the local network.

Settings

Setting	Default	Notes
postgresMajor	17	Must match the installed PostgreSQL tools.
database	staging	The main staging database.
appRole	stage_app	Worker role; not a superuser.
adminRole	stage_admin	Admin and backup role; separate from the Worker role.
port	Automatically selected	Saved once, normally in 55432–55531, and reused.
originAddress	127.0.0.1	The local PostgreSQL bind address.
postgres.dataDirectory	./data	PostgreSQL data directory.
postgres.tls.certFile	required	Externally provisioned server certificate.
postgres.tls.keyFile	required	Externally provisioned private key.
postgres.tls.caFile	none	Optional CA bundle.
cloudflareWorkers.tokenFile	none	A path to a local cloudflared token file.
backup.directory	./backups	Local backup directory.
backup.keepLocal	7	Number of complete local backup sets to keep.

The backup.intervalMinutes value is saved for future scheduling. In v1, a backup runs only when you call stage-pg backup <instance>.

Optional S3 upload

Add an s3 object under backup when you want stage-pg backup to upload the dump, checksum, and manifest:

{
  "backup": {
    "intervalMinutes": 360,
    "directory": "./backups",
    "keepLocal": 7,
    "s3": {
      "bucket": "my-staging-backups",
      "prefix": "stage-pg",
      "region": "auto",
      "endpoint": "https://s3.example.com",
      "forcePathStyle": false,
    },
  },
}

Supply credentials through the environment, not config.json:

export AWS_ACCESS_KEY_ID='…'
export AWS_SECRET_ACCESS_KEY='…'
export AWS_SESSION_TOKEN='…' # only when your credentials use one
stage-pg backup ./stage-data

If the upload fails, the verified local backup remains available and the failure is recorded in state.json and the manifest.

What not to put in config.json

Do not put any of these in the public configuration file:

• database passwords;
• the contents of the Cloudflare token file;
• S3 access keys;
• private keys.