# First Steps

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

```bash
cd apps/lerma
docker compose up -d db
```

This starts `postgres:16-alpine` for local development.

## 2. Install dependencies and set up the database

```bash
cd apps/lerma
mix setup
```

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

## 3. Run the dashboard

```bash
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`:

```bash
SKIP_AUTH=true mix phx.server
```

## 4. (Optional) Real Cloudflare Access login

To exercise the real JWT flow, create the local Access resources and start the
tunnel — see [Local Auth Setup](readme.html#local-auth-setup-cloudflare-access):

```bash
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`:

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

## 6. Verify your changes

```bash
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](deploy.html).