chadtmiller.com/monolith
An atproto PDS
0
0
# 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](contributing.md).
## 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 as `alice.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:
```sh
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:
```sh
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](https://knotless.dev/chadtmiller.com/monolith/releases)
lists every version. If you have the [knotless](https://knotless.dev) 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`:
```sh
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](deploying.md#the-environment) 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:
```sh
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:
```sh
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:
```sh
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:
```sh
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](../../spec/MIGRATION.md#createaccount-with-a-did)). 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](deploying.md): the rest of the environment, blobs in a
bucket, and backups.
- [Calling the server](calling.md): the `pds` CLI, XRPC and the MCP
endpoint, and connecting an AI app.
- [Operating](operating.md): the log, health, metrics and upgrades.