Skip to content

Deploying

Running the server on the network takes a bit more than Getting started shows. You’ll need the image, the address and proxy, the whole environment, blobs in a bucket and backups.

knotless.dev/chadtmiller.com/monolith is the server as an image. Its tag is latest or a version, and it’s published with each release for linux/amd64. It holds only pds on Debian slim and runs as the user pds, uid and gid 10001. It sets PDS_PORT=2583, PDS_BIND_ADDRESS=:: and PDS_DATA_DIR=/data, a volume that user must own. Its labels, org.opencontainers.image.version and org.opencontainers.image.revision, name the version and the commit it was built from, and /xrpc/_health answers with the version.

docker run -d -p 127.0.0.1:2583:2583 -v pds-data:/data --env-file pds.env knotless.dev/chadtmiller.com/monolith

Since the image holds only the pds binary, pds <group> <command> in it is the CLI, like anywhere else. To build it yourself from a clone, see Contributing.

docker stop sends SIGTERM, and the server shuts down within Docker’s 10 seconds (Operations).

Outside a container, the server listens on 127.0.0.1 unless PDS_BIND_ADDRESS names another address (The PDS: accounts and their records). Either way, it speaks plain HTTP, and the reverse proxy handles TLS.

Behind a proxy, set PDS_TRUSTED_PROXIES to the proxy’s addresses. The server reads X-Forwarded-For only from those peers. So if it isn’t set, every client shares the proxy’s rate limits (Limits).

When PDS_METRICS_PORT is set, /metrics listens only on 127.0.0.1. In a container, that means only what runs inside it can scrape it (Operating).

These are what a server on the network needs besides those above. Each variable’s page says the rest.

VariableWhat it does
PDS_HOSTNAME, PDS_PUBLIC_URLThe host name and its https:// URL. Passkeys are bound to the URL’s host (Passkeys). A browser won’t make one for an IP address, and once the URL names another host, the ones made before aren’t offered anymore
PDS_HANDLE_DOMAINSThe domains accounts’ handles end in, such as .example.com. Each handle’s own host must reach the server for /.well-known/atproto-did, so you need a wildcard DNS record and certificate
PDS_PLC_URLhttps://plc.directory
PDS_PLC_ROTATION_KEY_HEXA new secp256k1 key (openssl rand -hex 32), kept in a secret store. Whoever holds it controls every account’s DID
PDS_RECOVERY_DID_KEYA did:key whose private key is kept offline, so the DIDs outlive a lost or stolen rotation key
PDS_EMAIL_SMTP_URL, PDS_EMAIL_FROMThe mail server, and the address mail comes from
PDS_ADMIN_PASSWORD, PDS_INVITE_REQUIREDThe admin password, which also reads the log and stats (Operating). Invites are required (true) unless anyone may sign up
PDS_LOG_DIR, PDS_LOG_KEEP_BYTESA directory where the log is also kept, on its own volume apart from /data, so the admin can read it back across deploys. The second sets how much it keeps, 64 MiB by default
PDS_CRAWLERSThe relays the server tells about itself, such as https://bsky.network
PDS_BSKY_APP_VIEW_URL, PDS_BSKY_APP_VIEW_DID, PDS_BSKY_APP_VIEW_CDN_URL_PATTERNhttps://api.bsky.app, did:web:api.bsky.app and https://cdn.bsky.app/img/%s/plain/%s/%s@jpeg, for the Bluesky app
PDS_MAX_REPO_IMPORT_SIZEThe largest repository an account can bring when it moves here (Moving an account between servers), 300 MiB by default
PDS_BLOB_UPLOAD_LIMITThe largest blob an account can upload, 5 MiB by default (Limits). If accounts move here from a server that takes larger blobs (for video, say), set it at least that large, or they can’t bring all of theirs
PDS_BLOB_QUOTA_BYTESThe bytes of blobs an account can hold, 1 GiB by default (Limits). An uploadBlob past it is refused with 400 BlobQuotaExceeded, so when accounts move here, set it above the largest account’s blobs
PDS_RATE_LIMITS_ENABLEDtrue by default. Its uploads limit lets an account make 1000 uploadBlobs a day (Limits), so an account bringing more blobs than that brings them over several days, or while the server runs with false just for the move
PDS_HANDLE_DNS_SERVEROptional. The DNS server asked for a handle’s _atproto TXT record when an account takes a handle on its own domain (Identity). When it’s unset, the server uses the machine’s resolver
PDS_BLOBSTORE_S3_BUCKET and the rest of Blobs’sOptional. A bucket in an S3-compatible store to keep blobs in instead of the data directory (below)

PDS_DEV_MAIL_DIR, PDS_OAUTH_CLIENT_FETCH, PDS_HANDLE_FETCH and PDS_DISABLE_SSRF_PROTECTION are for development. Never set them on a server on the network.

When PDS_BLOBSTORE_S3_BUCKET is set, the server keeps blobs in that bucket of a store that speaks S3’s API (Amazon S3, Cloudflare R2, MinIO and the like). None of their bytes go in the data directory. The bucket’s region, endpoint, path style, credentials and timeouts have their own variables (Blobs).

The server picks where blobs live at its first start. To change it later, stop the server and move them. Run this with the environment pds serve gets, plus the bucket’s variables:

pds migrate-blobs --to bucket # or --to disk

Then start the server with the new variables. If a move gets killed part way, run it again to finish (Blobs).

Back the server up with snapshots of its volume or filesystem, taken while it runs. A snapshot is a data directory the server can start on, and it holds every write answered before it was taken (Durability).

A cp or rsync of a running server’s directory isn’t a backup. Stop the server first, or take a snapshot.

Keep the environment somewhere separate and safe, since the data directory doesn’t hold the PLC rotation key.

With blobs in a bucket, the snapshot doesn’t hold any blob bytes. Keep the bucket versioned, so a blob deleted after the snapshot can be restored along with it.

Starting on a backup rolls the server back. Anything written after it is lost, and relays and AppViews hold commits and firehose seqs the server doesn’t have anymore.