Configuration

DBDock can be configured via dbdock.config.json, environment variables, or a mix of both. Secrets always live in environment variables — never in the config file.

Security-first. Passwords, API keys, webhooks, and encryption secrets must be set via environment variables. The config file is designed to be committed to your repository; the .env file is designed not to be.

Config file structure

dbdock.config.json has four top-level sections:

{
  "database":  { /* connection details (no password) */ },
  "storage":   { /* storage provider config */ },
  "backup":    { /* format, compression, encryption, retention */ },
  "alerts":    { /* email & slack notifications */ }
}

Database

Option 1 — URL via environment (recommended)

Set DBDOCK_DB_URL or DATABASE_URL to a full PostgreSQL URL. When present, it overrides anything in dbdock.config.json.

DBDOCK_DB_URL=postgresql://user:password@host:5432/database
# or
DATABASE_URL=postgresql://user:password@host:5432/database

Option 2 — Config file with password in env

{
  "database": {
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "postgres",
    "database": "myapp"
  }
}

Password comes from DBDOCK_DB_PASSWORD.

Option 3 — `.pgpass`

For host-level credential isolation, use PostgreSQL’s .pgpass file:

touch ~/.pgpass
chmod 600 ~/.pgpass
echo "localhost:5432:myapp:postgres:my-secure-password" >> ~/.pgpass

DBDock uses .pgpass automatically when present.

Storage

Pick one provider. Each has its own dedicated page with setup instructions:

Local

Filesystem storage for single-server setups.

AWS S3

S3 or any S3-compatible service.

Cloudflare R2

Zero-egress object storage.

Cloudinary

Media platform with generous free tier.

Backup

{
  "backup": {
    "format": "custom",
    "compression": {
      "enabled": true,
      "level": 6
    },
    "encryption": {
      "enabled": true
    },
    "retention": {
      "enabled": true,
      "maxBackups": 100,
      "maxAgeDays": 30,
      "minBackups": 5,
      "runAfterBackup": true
    }
  }
}

Field	Type	Default	Description
`format`	`'custom' \| 'plain' \| 'directory' \| 'tar'`	`'custom'`	PostgreSQL backup format
`compression.enabled`	boolean	`true`	Apply zstd compression
`compression.level`	0–11	`6`	zstd compression level
`encryption.enabled`	boolean	`true`	AES-256-GCM encryption
`retention.enabled`	boolean	`true`	Enable automatic cleanup
`retention.maxBackups`	number	`100`	Cap total backup count
`retention.maxAgeDays`	number	`30`	Delete backups older than N days
`retention.minBackups`	number	`5`	Never delete below this count
`retention.runAfterBackup`	boolean	`true`	Run cleanup after each backup

Encryption key is read from DBDOCK_ENCRYPTION_SECRET. Generate a key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Alerts

See the dedicated alert pages for setup:

Email

SMTP via Gmail, SendGrid, SES, Mailgun, or any provider.

Slack

Incoming webhooks.

Environment variables reference

DBDock reads from both .env and .env.local. .env.local takes priority.

Database

Variable	Description
`DBDOCK_DB_URL`	Full PostgreSQL URL
`DATABASE_URL`	Same as `DBDOCK_DB_URL` (alternative name)
`DBDOCK_DB_PASSWORD`	Password (when not using URL form)
`DB_HOST`	Database host
`DB_PORT`	Database port
`DB_USER`	Database user
`DB_NAME`	Database name

Storage

Variable	Description
`STORAGE_PROVIDER`	`local` \| `s3` \| `r2` \| `cloudinary`
`STORAGE_BUCKET`	Bucket/container name
`STORAGE_LOCAL_PATH`	Path for local storage
`DBDOCK_STORAGE_ACCESS_KEY`	S3/R2 access key
`DBDOCK_STORAGE_SECRET_KEY`	S3/R2 secret key
`DBDOCK_CLOUDINARY_API_KEY`	Cloudinary API key
`DBDOCK_CLOUDINARY_API_SECRET`	Cloudinary API secret

Encryption

Variable	Description
`DBDOCK_ENCRYPTION_SECRET`	64-char hex key
`ENCRYPTION_ENABLED`	`true` \| `false`
`ENCRYPTION_ITERATIONS`	PBKDF2 iterations (default `100000`)

Alerts

Variable	Description
`DBDOCK_SMTP_USER`	SMTP username
`DBDOCK_SMTP_PASS`	SMTP password
`DBDOCK_SLACK_WEBHOOK`	Slack incoming webhook URL
`DBDOCK_CUSTOM_WEBHOOK`	Custom HTTP webhook URL

Runtime

Variable	Description
`DBDOCK_CONFIG_PATH`	Path to `dbdock.config.json` (default: `./dbdock.config.json`)
`DBDOCK_STRICT_MODE`	`true` to refuse any secret read from the config file

Strict mode

Set DBDOCK_STRICT_MODE=true to enforce environment-only secrets. DBDock will refuse to load any configuration where a secret appears in the config file, preventing accidental commits. Recommended for CI and production.

Config migration

If you have secrets in dbdock.config.json from an older version:

npx dbdock migrate-config

DBDock moves them to .env, cleans up the config file, and updates .gitignore. See migrate-config.

Get Started

Core Concepts

DBDock Cloud

Cloud Sync

Security

Guides

Help

Config file structure

Database

Option 1 — URL via environment (recommended)

Option 2 — Config file with password in env

Option 3 — `.pgpass`

Storage

Local

AWS S3

Cloudflare R2

Cloudinary

Backup

Alerts

Email

Slack

Environment variables reference

Database

Storage

Encryption

Alerts

Runtime

Strict mode

Config migration

​Config file structure

​Database

​Option 1 — URL via environment (recommended)

​Option 2 — Config file with password in env

​Option 3 — .pgpass

​Storage

Local

AWS S3

Cloudflare R2

Cloudinary

​Backup

​Alerts

Email

Slack

​Environment variables reference

​Database

​Storage

​Encryption

​Alerts

​Runtime

​Strict mode

​Config migration

Config file structure

Database

Option 1 — URL via environment (recommended)

Option 2 — Config file with password in env

Option 3 — `.pgpass`

Storage

Backup

Alerts

Environment variables reference

Database

Storage

Encryption

Alerts

Runtime

Strict mode

Config migration