Getting started

lyrid is a web service: a Rust API over PostgreSQL, a React SPA, and this documentation site. At the foundation stage there is no deployment yet, so “getting started” means running the three pieces on your own machine.

What you need

• Rust — at least the version in rust-version in Cargo.toml. rustup update stable is enough.
• Node LTS with pnpm — corepack enable provides pnpm.
• Docker — only for the development database; nothing else runs in a container.

The database

The compose file brings up PostgreSQL alone, configured to match the example environment:

docker compose up -d db

Copy the example environment; its DATABASE_URL already points at that container:

cp .env.example .env

The API

cargo run -- serve

serve is also what running the binary with no arguments does, which is what a container image or a service unit expects.

The server binds 0.0.0.0:8080 (override with LYRID_ADDR), applies any pending migrations on start, and serves /health:

curl http://127.0.0.1:8080/health

{ "status": "ok", "version": "0.1.0", "database": "ok" }

If the database is unreachable the same endpoint answers 503 with "status": "degraded" — the process is alive but cannot do its job, and the two cases are worth telling apart.

The universe

An empty database is a sky with no stars. Filling it takes three imports, in this order:

cargo run -- import musicbrainz  --dump ./mbdump.tar.bz2                   # the stars
cargo run -- import listenbrainz --dump ./artist-credit-relations.tar.bz2  # the routes between them
cargo run -- import discogs      --masters ./discogs_masters.xml.gz \
                                 --labels  ./discogs_labels.xml.gz         # what each star is made of

MusicBrainz comes first in every case: both later imports resolve against the canon it builds.

See Importing MusicBrainz, Importing similarity and Importing genres and labels. Everything else runs fine without them; there is simply nothing to look at yet.

Adding a migration

Migrations are embedded into the binary at compile time, so a newly added .sql file needs a rebuild before it will apply — cargo build after adding one, or the server will happily run the old set.

The SPA

cd web
pnpm install
pnpm dev

Vite serves the SPA on http://127.0.0.1:5173 and proxies /health and /api to the API, so the browser only ever talks to one origin and no CORS configuration is needed.

This site

cd docs/site
pnpm install
pnpm dev

Checks before a commit

The same gate CI runs:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cd web && pnpm lint && pnpm build
cd docs/site && pnpm build