pegasus#

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

table of contents#

• Running It
• Environment
  • SMTP
  • S3
• Development
• Libraries
  • ipld - IPLD implementation (CIDs, CAR, DAG-CBOR)
  • kleidos - Cryptographic key management
  • mist - Merkle Search Tree implementation
  • hermes - XRPC client
  • frontend - Web interface
  • pegasus - PDS implementation

running it#

After cloning this repo, start by running

docker compose pull

to pull the latest image, or

docker compose build

to build from source.

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.

libraries#

This repo contains several libraries in addition to the pegasus PDS. Each library has its own README with detailed documentation.

ipld#

A mostly DASL-compliant implementation of CIDs, CAR, and DAG-CBOR.

Provides content addressing primitives for IPLD: Content Identifiers (CIDs), Content Addressable aRchives (CAR), and deterministic CBOR encoding.

kleidos#

An atproto-valid interface for secp256k1 and secp256r1 key management, signing/verifying, and encoding/decoding.

Handles cryptographic operations for both K-256 and P-256 elliptic curves with multikey encoding and did:ket generation.

mist#

A Merkle Search Tree implementation for data repository purposes with a swappable storage backend.

hermes#

An XRPC client for atproto with three components:

• hermes - Core XRPC client library
• hermes_ppx - PPX extension for ergonomic API calls
• hermes-cli - CLI to generate OCaml types from atproto lexicons

frontend#

The PDS frontend, containing the admin dashboard and account page.

pegasus#

The PDS implementation.

development#

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 and email templates are written in MLX, a JSX-ish OCaml dialect. To format them, you'll need to opam install ocamlformat-mlx, then ocamlformat-mlx -i ./{frontend,pegasus}/**/*.mlx.