~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
143 lines · 5.3 KB Raw History

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 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:

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 pds CLI, XRPC and the MCP endpoint, and connecting an AI app.
  • Operating: the log, health, metrics and upgrades.