chadtmiller.com/monolith
An atproto PDS
Getting started
You'll take Monolith from nothing to an account you sign in to from the Bluesky app. You get the server, give it its settings, run it behind your proxy and make the first account. You don't need a clone of the repository, since that's for contributing.
What you need
- A Linux server, x86-64, with a volume for the data.
- A domain with two DNS records pointing at the server. One is the
server's own name, such as
pds.example.com, and the other is a wildcard under it,*.pds.example.com. Each account's handle is a name under it, such asalice.pds.example.com, and each one must reach the server. - A reverse proxy that holds a TLS certificate for both names and passes their requests to the server. The server speaks plain HTTP.
- An SMTP server to send mail through, for sign-up confirmations and password resets.
Get Monolith
Pull the image:
docker pull knotless.dev/chadtmiller.com/monolith
That's the latest version. A tag pins one, such as
knotless.dev/chadtmiller.com/monolith:0.2.0. The image holds only the
pds binary on Debian slim. It runs as its own user and keeps its data on
the volume /data. Its labels name its version and the commit it was
built from (org.opencontainers.image.version and .revision).
Or get the binary for Linux x86-64 from the releases page:
v=0.2.0
curl -fLO https://knotless.dev/chadtmiller.com/monolith/releases/download/pds/$v/pds-$v-x86_64-linux.tar.gz
curl -fL https://knotless.dev/chadtmiller.com/monolith/releases/download/pds/$v/pds-$v-x86_64-linux.tar.gz.sha256 | sha256sum -c
tar xzf pds-$v-x86_64-linux.tar.gz && sudo install pds /usr/local/bin/
The releases page
lists every version. If you have the knotless CLI,
knotless release download knotless://chadtmiller.com/monolith pds fetches
the latest and checks each file against its release.
pds is one program. pds serve runs the server, and
pds <group> <command> is the CLI that calls one.
Configure it
The server reads its settings from its environment. Put them in a file,
pds.env:
PDS_HOSTNAME=pds.example.com
PDS_PUBLIC_URL=https://pds.example.com
PDS_HANDLE_DOMAINS=.pds.example.com
PDS_PLC_URL=https://plc.directory
PDS_PLC_ROTATION_KEY_HEX= # openssl rand -hex 32
PDS_EMAIL_SMTP_URL=smtps://user:password@smtp.example.com
PDS_EMAIL_FROM=pds@example.com
PDS_ADMIN_PASSWORD= # openssl rand -hex 16
PDS_INVITE_REQUIRED=true
PDS_TRUSTED_PROXIES=172.17.0.1 # where your proxy's requests come from
PDS_CRAWLERS=https://bsky.network
PDS_BSKY_APP_VIEW_URL=https://api.bsky.app
PDS_BSKY_APP_VIEW_DID=did:web:api.bsky.app
PDS_BSKY_APP_VIEW_CDN_URL_PATTERN=https://cdn.bsky.app/img/%s/plain/%s/%s@jpeg
Keep this file safe. Whoever holds the rotation key controls every account's DID, and the data directory doesn't keep a copy. If you lose it, the server can't change its accounts' DIDs anymore, which a new handle needs. Deploying says what each setting is for and what else there is, such as a recovery key kept offline.
PDS_TRUSTED_PROXIES says where the proxy's requests come from. If the
proxy is on the same machine and the server runs in Docker, that's the
bridge's gateway, usually 172.17.0.1. With the binary, it's 127.0.0.1.
If it isn't set, every client shares the proxy's rate limits.
Run it
With Docker:
docker run -d --name monolith --restart unless-stopped \
-p 127.0.0.1:2583:2583 -v pds-data:/data --env-file pds.env \
knotless.dev/chadtmiller.com/monolith
Or run the binary, with its data in a directory of its own:
set -a; . ./pds.env; set +a
PDS_PORT=2583 PDS_DATA_DIR=/var/lib/monolith pds serve
Either way, it listens on 127.0.0.1:2583. Point the proxy's two names at
that address, then check that it answers through the proxy:
curl https://pds.example.com/xrpc/_health
Make the first account
The CLI calls the server that PDS_URL names. With the binary, run pds
as it is. With Docker, run it as docker run --rm -e PDS_URL -e PDS_ADMIN_PASSWORD knotless.dev/chadtmiller.com/monolith, which passes on
whichever of those is set.
Make an invite code as the admin, then create the account with it:
export PDS_URL=https://pds.example.com
PDS_ADMIN_PASSWORD=… pds server create-invite-code --use-count 1
pds server create-account --handle alice.pds.example.com \
--email alice@example.com --password '…' --invite-code <the code>
The admin password goes only with the first command. When it's set, the
CLI calls as the admin, and createAccount doesn't take an admin
(MIGRATION.md). The
server makes the account's DID and registers it with the PLC directory
when it creates the account.
Sign in
In the Bluesky app, sign in with alice.pds.example.com and its password,
and choose the custom hosting provider https://pds.example.com. An app
that signs in with OAuth sends you to the server's own sign-in page
instead.
Next
- Deploying: the rest of the environment, blobs in a bucket, and backups.
- Calling the server: the
pdsCLI, XRPC and the MCP endpoint, and connecting an AI app. - Operating: the log, health, metrics and upgrades.