pegasus#

is an atproto PDS, along with an assortment of atproto-relevant libraries, written in OCaml.

running it#

After cloning this repo, start by running

docker compose build

Next, run

docker compose run --rm --entrypoint gen-keys pds

to generate some of the environment variables you'll need.

Copy .env.example to .env and fill in the environment variables marked as required. See Environment for further details on configuration.

After that, run

docker compose up -d

to start the PDS, then navigate to https://{PDS_HOSTNAME}/admin to log in with the admin password you specified and create an invite code or a new account on the PDS.

environment#

Documentation for most environment variables can be found in .env.example. There are two optional categories of environment variables that add functionality:

SMTP#

The PDS can email users for password changes, identity updates, and account deletion. If these environment variables are not set, emails will instead be logged to the process' stdout.

• PDS_SMTP_AUTH_URI — The URI to connect to the mail server. This should look like smtp[s]://user:pass@host[:port].
• PDS_SMTP_STARTTLS=false — Whether to use STARTTLS when connecting to the mail server. Defaults to false. If true, the connection will default to port 587. If false, the connection will default to port 465. Setting a port in PDS_SMTP_AUTH_URI will override either one.
• PDS_SMTP_SENDER — The identity to send emails as. Can be an email address (e@mail.com) or a mailbox (Name <e@mail.com>).

S3#

The PDS can be configured to back up server data to and/or store blobs in S3(-compatible storage).

• PDS_S3_BLOBS_ENABLED=false — Whether to store blobs in S3. By default, blobs are stored locally in {PDS_DATA_DIR}/blobs/[did]/.
• PDS_S3_BACKUPS_ENABLED=false — Whether to back up data to S3.
• PDS_S3_BACKUP_INTERVAL_S=3600 — How often to back up to S3, in seconds.
• PDS_S3_ENDPOINT, PDS_S3_REGION, PDS_S3_BUCKET, PDS_S3_ACCESS_KEY, PDS_S3_SECRET_KEY — S3 configuration.
• PDS_S3_CDN_URL — You may optionally set this to redirect getBlob requests to {PDS_S3_CDN_URL}/blobs/{did}/{cid}. When unset, blobs will be fetched either from local storage or from S3, depending on PDS_S3_BLOBS_ENABLED.

development#

This repo contains several libraries in addition to the pegasus PDS:

To start developing, you'll need:

• opam, the OCaml Package Manager
• and the following packages, or their equivalents on your operating system: cmake git libev-dev libffi-dev libgmp-dev libssl-dev libsqlite3-dev libpcre3-dev pkg-config

Start by creating an opam switch; similar to a Python virtual environment, storing the dependencies for this project and a specific compiler version. After that, install dune, the build system/package manager pegasus uses.

opam switch create . 5.2.1 --no-install
opam install dune

You may need to run eval $(opam env) for this to work. Next, run

dune pkg lock

to solve dependencies.

Set the required environment variables (see Environment), noting that the program won't automatically read from .env, then either run

dune exec pegasus

to run the program directly, or

dune build

to produce an executable that you'll likely find in _build/default/bin.

For development, you'll also want to run

dune tools exec ocamlformat
dune tools exec ocamllsp

to download the formatter and LSP services. You can run dune fmt to format the project.

The frontend is written in MLX, a JSX-ish OCaml dialect. To format it, you'll need to opam install ocamlformat-mlx, then ocamlformat-mlx -i frontend/**/*.mlx. You'll see a few errors on formatting files containing [%browser_only]; I'm waiting on the next release of mlx to fix those.