# The andon-server command

`andon-server` runs the portable server: the board, its API and its database migrations, on any Node host with
Postgres. It reads its settings from the environment ([environment variables](https://andon-docs.pages.dev/reference/env.md#the-server)).

From a checkout, run it as `node apps/server/src/cli.ts <command>`, or through the `pnpm` scripts below. Every command
and flag is checked against the code by a test (`apps/server/test/reference-docs.test.ts`).

| Command | What it does | `pnpm` script |
|---|---|---|
| `andon-server start` | Apply pending migrations, then serve the API (and the built board, when there is one) on `PORT` (default 8787). | `pnpm dev:server` |
| `andon-server migrate` | Apply `db/migrations` to `DATABASE_URL_DIRECT` (or `DATABASE_URL`), then sync the AI switches with the environment. | |
| `andon-server up` | Andon on this machine in one command: Postgres, the server with the board on port 8787, and this machine's agent, with the data in `~/.andon`. | `pnpm andon:up` |
| `andon-server db start\|stop\|reset\|status\|url` | This checkout's own local Postgres, for development. | `pnpm db:local …` |
| `andon-server rotate-secrets` | Re-encrypt the stored secrets under the current `ANDON_SECRET_KEY`. | |

## `andon-server up`

The first run opens `/setup` in the browser, waits for you to make the owner account, then enrolls this machine's agent
into the new org. Later runs start whatever isn't running. On Windows it starts Postgres and the server but not the
agent.

| Flag | What it does |
|---|---|
| `--stop` | Stop the agent, the server and Postgres. The data stays. |
| `--reset` | Stop, then start again with an empty database. The old files and the agent's config are set aside, not deleted. |
| `--no-browser` | Don't open the browser. |
| `--url <address>` | Serve it as this address, such as a reverse proxy's `https://` name. Later runs keep it; `--url auto` goes back to the address below. |

The server's own address (`ANDON_URL`) is the one `--url` set. Without one, it's this machine's HTTPS address on the
tailnet once `tailscale serve` shares it, else `http://localhost:8787`. Passkeys and the links the server builds use
it. When the server runs on another address, `andon up` restarts it. `localhost` keeps working beside it.

`ANDON_UP_HOME` moves `~/.andon`, and `ANDON_UP_PORT` changes the port.

## `andon-server db`

| Subcommand | What it does |
|---|---|
| `db start` | Start this checkout's Postgres (in `.andon/pg`), create the `andon` database, migrate it, and print its `DATABASE_URL`. |
| `db url` | The same, printing only the `DATABASE_URL`. |
| `db reset` | Drop and recreate the `andon` database, then migrate it. |
| `db status` | Whether it's running, and on which port. |
| `db stop` | Stop it. |

## `andon-server rotate-secrets`

To change `ANDON_SECRET_KEY`:

1. Set the new key as `ANDON_SECRET_KEY` and the old one as `ANDON_SECRET_KEY_PREVIOUS` (comma-separate several).
2. Run `andon-server rotate-secrets`.
3. When it says every secret is under `ANDON_SECRET_KEY`, remove `ANDON_SECRET_KEY_PREVIOUS`.

A secret that neither key decrypts is left alone and named, and the command exits 1: add its key, or set that secret
again.
