First Steps

On this page

1. Start the local database
2. Install dependencies and set up the database
3. Run the dashboard
4. (Optional) Real Cloudflare Access login
5. Generate the API docs
6. Verify your changes
7. Deploy

A guided path from a fresh clone to a running Lerma dashboard, passing checks, and (optionally) a real Cloudflare Access login.

1. Start the local database

cd apps/lerma
docker compose up -d db

This starts postgres:16-alpine for local development.

2. Install dependencies and set up the database

cd apps/lerma
mix setup

mix setup fetches deps, creates and migrates the database, and seeds it.

3. Run the dashboard

cd apps/lerma
mix phx.server

Open http://localhost:4000. Auth is verified against Cloudflare Access, so for local work either use the tunnel flow below or set SKIP_AUTH=true:

SKIP_AUTH=true mix phx.server

To exercise the real JWT flow, create the local Access resources and start the tunnel — see Local Auth Setup:

cd apps/lerma/iac/tf
tofu workspace new local
tofu workspace select local
(set +a && source ../../.env && set -a && tofu apply)

# then, in another terminal
cd apps/lerma
CLOUDFLARED_TUNNEL_TOKEN=<token> bin/local-tunnel.sh

Visit https://local.lerma.paso4.io.

5. Generate the API docs

Lerma’s HexDocs-format API documentation is generated with ExDoc and served at /docs:

cd apps/lerma
mix docs     # writes priv/static/docs/index.html

6. Verify your changes

cd apps/lerma
mix format --check-formatted
mix credo --strict
mix test

# from the repository root
mix license_audit
mix precommit

7. Deploy

Deployment is automated through GitHub Actions (staging on develop, production on release). For the manual runbook — OpenTofu, Ansible, migrations, DNS, and GitHub secrets — read Deployment.