chadtmiller.com/monolith
An atproto PDS
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.
The image
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.md).
Address, TLS and proxies
Outside a container, the server listens on 127.0.0.1 unless
PDS_BIND_ADDRESS names another address
(PDS.md). 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.md).
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).
The environment
These are what a server on the network needs besides those above. Each variable's page says the rest.
| Variable | What it does |
|---|---|
PDS_HOSTNAME, PDS_PUBLIC_URL | The host name and its https:// URL. Passkeys are bound to the URL's host (PASSKEYS.md). 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_DOMAINS | The 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_URL | https://plc.directory |
PDS_PLC_ROTATION_KEY_HEX | A new secp256k1 key (openssl rand -hex 32), kept in a secret store. Whoever holds it controls every account's DID |
PDS_RECOVERY_DID_KEY | A did:key whose private key is kept offline, so the DIDs outlive a lost or stolen rotation key |
PDS_EMAIL_SMTP_URL, PDS_EMAIL_FROM | The mail server, and the address mail comes from |
PDS_ADMIN_PASSWORD, PDS_INVITE_REQUIRED | The 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_BYTES | A 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_CRAWLERS | The 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_PATTERN | https://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_SIZE | The largest repository an account can bring when it moves here (MIGRATION.md), 300 MiB by default |
PDS_BLOB_UPLOAD_LIMIT | The largest blob an account can upload, 5 MiB by default (LIMITS.md). 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_BYTES | The bytes of blobs an account can hold, 1 GiB by default (LIMITS.md). 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_ENABLED | true by default. Its uploads limit lets an account make 1000 uploadBlobs a day (LIMITS.md), 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_SERVER | Optional. The DNS server asked for a handle's _atproto TXT record when an account takes a handle on its own domain (IDENTITY.md). When it's unset, the server uses the machine's resolver |
PDS_BLOBSTORE_S3_BUCKET and the rest of BLOBS.md's | Optional. 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.
Blobs in a bucket
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.md).
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.md).
Backups
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.md).
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.