chadtmiller.com/monolith
An atproto PDS
0
0
# Contributing
A change goes spec first, then the harness, then the server.
[AGENTS.md](../../AGENTS.md#how-a-change-is-made) says how, and lists the
rules an agent building the server is given. Here you'll set up a clone of
the repository, see the checks a change has to meet, and see how a release
is made. You don't need a clone to run Monolith.
[Getting started](getting-started.md) starts from its image or its download.
## Working from a clone
```sh
git clone knotless://chadtmiller.com/monolith
```
The clone needs:
- Rust, through [rustup](https://rustup.rs). The Justfile runs cargo as
`rustup run stable cargo`.
- Node, at the version [`.node-version`](../../.node-version) names (24).
- [just](https://github.com/casey/just), which runs the
[Justfile](../../Justfile)'s targets, and `jq` for the sign-in below.
- The harness's and the pages' packages, installed once:
```sh
cd harness && npm ci && cd ..
cd web && npm ci && cd ..
```
- Chromium, but only for the harness's `--pages` run and `just look`:
```sh
cd harness && npx playwright install chromium
```
### Build
```sh
just build
```
This builds the authorization pages in `web/` into `web/dist`, then builds
`pds` into `target/release/pds`, which embeds them. The
[Dockerfile](../../Dockerfile) builds the image the same way:
```sh
docker build -t monolith .
```
### Run a server to try
```sh
just dev --seed
```
`just dev` builds `pds`, then runs
[`harness/dev.mjs`](../../harness/dev.mjs). That starts the server at
`http://localhost:2583`, with its own PLC directory in memory and an
AppView that points nowhere. What the server serves itself, such as
preferences, works, but anything it would forward to an AppView fails. Its
URL is `localhost`, not an IP address, so a browser will make and use
passkeys there ([PASSKEYS.md](../../spec/PASSKEYS.md#the-relying-party)).
`pds passkey add` gives you a link to open, and the authorization page
then offers the passkey.
Its files go in `target/dev/`: the data in `target/dev/data`, the
server's log in `target/dev/server.log`, and mail in `target/dev/mail`.
Each start makes `target/dev/` afresh.
It prints where the server and its PLC directory are, the `export` lines
the CLI needs, and where MCP is, then runs until Ctrl-C.
The flags:
- `--seed` makes `alice.test`, `bob.test` and `carol.test`, each with the
password `password`, if they aren't there already.
- `--keep` carries on from the last run: the same data, the same rotation
key, and the DIDs' operations, given to the new PLC directory again.
Each stop saves them in `target/dev/plc.json`.
- `--port <n>` listens on another port.
- `-- <command...>` runs another server command instead of
`../target/release/pds serve`.
The admin's password is `admin`, and handles end in `.test`.
Put `target/release/pds` on your `PATH` and paste the `export` lines it
printed. Then you're `alice.test`:
```sh
export PDS_URL=http://localhost:2583 PDS_ADMIN_PASSWORD=admin
export PDS_TOKEN=$(pds server create-session --identifier alice.test --password password | jq -r .accessJwt)
pds repo create-record --collection com.example.note --record '{"text":"hi"}'
pds repo list-records --collection com.example.note --limit 5
```
`just dev` sets no SMTP server, so no mail leaves the machine. Each email
the server would send, such as a confirmation or password reset token,
goes to `target/dev/mail/` as its own JSON file, `{"to", "kind",
"token"}` ([EMAIL.md](../../spec/EMAIL.md#the-development-sink)).
Ctrl-C stops it. The server shuts down and the PLC directory's operations
get saved, so `just dev --keep` carries on from there.
## The just targets
The [Justfile](../../Justfile) holds them:
```sh
just test # the crates' own tests
just quick # a short harness run of each kind, for while working
just code # the code gates (below)
just perf # the performance step
just gates # the code gates, the tests and the harness runs
just nightly # the long crash runs, then the performance step
just look consent # an authorization page drawn, desktop light and phone dark, in target/look
just dev --seed # a server to try by hand (above)
just docs-site # the documentation site, served while you write (below)
just docs-deploy # the documentation site, deployed by its owner (below)
```
While you work, run `just quick` by itself, with nothing else running.
Push the branch and open the pull early, since the gates run on the
runner.
## The gates
`just gates` runs the code gates, the tests and the harness side by side
([`harness/gates.mjs`](../../harness/gates.mjs)). The harness does several
runs at once (`GATES_JOBS` sets how many), and one of them is a short run
with the server killed every 15 steps.
The `gates` workflow
([`.knotless/workflows/gates.yml`](../../.knotless/workflows/gates.yml))
runs them on every pull into `main`, and on every push to it, that changes
what they check. That's the server's source and build, the pages it
embeds (`web/`), the data and lexicons it reads from `spec/`, and the
harness the gates run. A change that touches none of those, such as the
README, `docs/`, the spec's prose, the benchmark or the compatibility
check, is filed as skipped, and the merge queue takes that as passing.
## Nightly
`just nightly` runs the long crash runs, which kill the server every 15
steps over runs of 1000. Then it runs the performance step on its own. That
measures the server's speed against the reference's and against its
baseline, and what it holds once subscribers have come and gone, with its
whole output in the log. Last comes the scale run, which measures the
server's starts.
The `nightly` workflow
([`.knotless/workflows/nightly.yml`](../../.knotless/workflows/nightly.yml))
runs them on `main`'s tip every night at 10:00 UTC. The owner can also ask
for it on `main` or on a branch, for example for a pull that changes how
the server stores its data:
```sh
knotless run rerun --ref main --workflow nightly
knotless run rerun --ref refs/heads/<branch> --workflow nightly
```
## The code gates
Besides the harness and the tests, the source itself has to pass these,
the `code` gates. They're part of what `just gates` and the `gates`
workflow run. `just code` runs only them, and so does `node gates.mjs code`
in `harness/`, with `CARGO` naming the cargo to run.
- `cargo fmt --all --check`: the code is formatted the way rustfmt
formats it.
- `cargo clippy --workspace --all-targets -- -D warnings`: there's no
clippy or rustc warning in any target.
- `cargo deny check` ([`deny.toml`](../../deny.toml)): every dependency is
under a licence on the allowlist, and they're all permissive. There's no
advisory from the RustSec database, unmaintained and unsound crates
included, no yanked version and no wildcard version. Crates come only
from crates.io.
- `#![forbid(unsafe_code)]` sits at the root of every crate and each of
its targets, and `harness/code.mjs` checks it. Anything that needs the
operating system goes through a crate that wraps it safely.
- Every citation of the spec in the harness, such as `(spec/LIFECYCLE.md,
"deactivateAccount")`, names a section its page has. Every section of
every page is cited by some check, except the few that
`harness/spec-coverage.mjs` lists as unchecked, each with why
(`spec/PDS.md`, "How it is checked"). The `citations` workflow runs only
this check on every pull that changes a spec page or the harness. So a
pull of the spec's prose, which the gates skip, still has to pass it.
- The pages' source ([web/AGENTS.md](../../web/AGENTS.md)) has its own
checks. Each component uses only its own layer and those below it
(`harness/layers.mjs`), and every text colour reaches 4.5:1 on what it's
drawn on in light and dark (`harness/contrast.mjs`). `svelte-check`
gives no warning.
## The pages, by eye
`just look` draws an authorization page in a browser, in any state, and
saves pictures of it in `target/look` for you to open:
```sh
just look consent --scope 'atproto repo:*'
```
## The documentation site
`docs-site/` builds the site from these guides, the spec's pages, the
lexicons, and `compat/` and `bench/`. Its landing page,
`docs-site/src/pages/index.astro`, holds the photograph, a headline, one
sentence and two buttons. Its words follow
[the landing skill](../../.claude/skills/landing/SKILL.md), and its one
figure is read from the last benchmark, `bench/results.json`. Build it
with:
```sh
cd docs-site && npm ci && npm run build
```
The build fails on a link to a file or heading that isn't there, a method
`spec/PDS.md` lists under no page, or a variable the spec names in no
table. The `docs` workflow builds it on each pull that
changes what it's made from. `just docs-site` serves it at
http://localhost:4321/ while you write.
The site is at https://chadtmiller-com.knotless.page/monolith/. The `docs`
workflow deploys it on each push to `main` that changes what it's made
from, signed in with the owner's app password (`RELEASE_PASSWORD`). The
owner can also deploy it by hand after `knotless login`:
```sh
just docs-deploy
```
## Releases
A pull that changes what people running or calling the server see (its
behaviour, its settings, its CLI, its image) adds a change file to
`.changeset/`. `knope document-change` asks for the bump (`patch`,
`minor` or `major`) and a summary, or you can write it by hand like the
ones already there. Its heading and text become that change's entry in
`CHANGELOG.md`, so write them for those readers rather than for us. A
change they don't see, such as a test or the harness, adds none.
A release is `main` with the workspace's `version` raised and tagged
`v<version>`. Two workflows make it:
- `release-pull.yml` runs each day when `main` has change files. It runs
`knope release` on `main`'s tip, which raises the version, writes the
version's section of `CHANGELOG.md` and removes the change files. The
result is the one open pull, `Release <version>`, kept up to date as
change files land. Queueing that pull is the release. On 0.x, `minor`
raises the minor version, where knope by itself would raise the patch.
`knotless run rerun
knotless://chadtmiller.com/monolith --ref refs/heads/main --workflow
release-pull` makes the pull at once.
- `release.yml` runs once that pull lands and the gates pass at it. It
builds the pages and `pds` the way the Dockerfile does, and makes the
image from the binary with no container engine (`.knotless/image.sh`,
since the runner's jobs have none). It publishes both, each with the
version's changelog as its notes: the image as the package `monolith`,
and `pds-<version>-x86_64-linux.tar.gz` with its `.sha256` as the
package `pds`. Then it tags the commit. When you ask for it on a branch,
it builds both and publishes nothing.
Both run on `runner.knotless.dev` with `RELEASE_PASSWORD`, an app password
of the owner's, sealed to it only for pushes to `main`.
Once the release is tagged, write `harness/upgrade/` again with its binary
and commit it:
```sh
git worktree add ../pds-release v<version> && (cd ../pds-release/web && npm ci) && (cd ../pds-release && just build)
cd harness && node compare.mjs --upgrade-write -- ../../pds-release/target/release/pds serve
```
That binary is then the previous version every later build must start on
(`compare.mjs --upgrade`, in [Comparing](comparing.md#the-store-scale-and-upgrades)).