Configuration

All configuration is passed through environment variables set on the container, either from your compose file or the image defaults. On first start the entrypoint also copies them into /pds/pds.env, which is what pdsadmin reads.

Image defaults differ from upstream

This image ships a few defaults that differ from the upstream PDS. Most notably PDS_BLOB_UPLOAD_LIMIT is raised to 50MB, and PDS_INVITE_REQUIRED is pinned to true so registration stays invite-only.

Why these defaults are baked in

Some values look like duplicates of upstream defaults but are load-bearing. They are set by the image so the PDS behaves correctly out of the box.

PDS_BLOB_UPLOAD_LIMIT: the PDS falls back to 5 * 1024 * 1024 (5MB) when this is unset. The image's 52428800 (50MB) is a deliberate override. Remove it and uploads silently drop to 5MB.
PDS_DATA_DIRECTORY: structural. When unset, the PDS writes its SQLite databases to the working directory (/app) instead of the /pds volume, so data would not persist across restarts. It must stay set.

Required¶

These have no default. The container will not start until each one is set. See Installation for the secret-generation commands.

Variable	Description
`PDS_HOSTNAME`	Public hostname of the PDS, for example `pds.example.com`.
`PDS_JWT_SECRET`	Random secret for signing JWTs. `openssl rand --hex 16`.
`PDS_ADMIN_PASSWORD`	Password for the admin account. `openssl rand --hex 16`.
`PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX`	64 character hex (256 bit) secp256k1 private key.

Optional¶

The default column shows the effective value, whether set by the image or applied by the PDS internally. Entries marked None are unset and have no value until you provide one. The full upstream list lives in packages/pds/src/config/env.ts.

Variable	Default	Description
`PDS_INVITE_REQUIRED`	`true`	Require an invite code to register. Keep `true` to block spam signups.
`PDS_HCAPTCHA_SITE_KEY`	None	hCaptcha site key. Enables captcha on registration when set.
`PDS_HCAPTCHA_SECRET_KEY`	None	hCaptcha secret key, paired with the site key.
`PDS_HCAPTCHA_TOKEN_SALT`	None	Salt used when hashing hCaptcha tokens.
`PDS_CONTACT_EMAIL_ADDRESS`	(empty)	Contact email advertised via `describeServer`. Set to your address.
`PDS_BLOB_UPLOAD_LIMIT`	`52428800`	Max blob upload size in bytes (50MB). The PDS falls back to 5MB when unset.
`PDS_PORT`	`3000`	Port the PDS listens on inside the container.
`EUID`	`1000`	User ID the service runs as.
`EGID`	`1000`	Group ID the service runs as.
`PDS_DATA_DIRECTORY`	`/pds`	Data directory inside the container.
`PDS_BLOBSTORE_DISK_LOCATION`	`/pds/blocks`	Blob storage location.
`PDS_DID_PLC_URL`	`https://plc.directory`	PLC directory service.
`PDS_BSKY_APP_VIEW_URL`	`https://api.bsky.app`	AppView service URL.
`PDS_BSKY_APP_VIEW_DID`	`did:web:api.bsky.app`	AppView service DID.
`PDS_REPORT_SERVICE_URL`	`https://mod.bsky.app`	Moderation report service URL.
`PDS_REPORT_SERVICE_DID`	`did:plc:ar7c4by46qjdydhdevvrndac`	Moderation report service DID.
`PDS_CRAWLERS`	`https://bsky.network`	Relay crawlers to notify of updates.
`LOG_ENABLED`	`true`	Emit logs to stdout.
`PDS_EMAIL_SMTP_URL`	None	SMTP URL and authentication for outbound email.
`PDS_EMAIL_FROM_ADDRESS`	None	From address for outbound email.
`PDS_PRIVACY_POLICY_URL`	None	Privacy policy link advertised via `describeServer`.
`PDS_TERMS_OF_SERVICE_URL`	None	Terms of service link advertised via `describeServer`.
`PDS_RATE_LIMITS_ENABLED`	`true`	Enable request rate limiting.

Deprecated: PUID and PGID

Older versions used PUID and PGID. They still work as aliases for EUID and EGID but print a deprecation notice on start. Use EUID and EGID.