# Deploy Andon

Deploy Andon when a team shares one board, or when the board has to stay up while your computer sleeps. An instance
is one server, which also serves the board, and one Postgres 15 or newer from any provider. The code is the same on
every host.

Everyone on a shared board adds their own machines, and each person's cards run only on their own machines. The
server runs no cards itself.

To try Andon on your own computer instead, use [the desktop app](https://andon-docs.pages.dev/guide/desktop-app.md), or
[`pnpm andon:up`](#run-it-from-a-clone) from a clone.

## Choose a host

Andon runs in one of two shapes. Pick the one that fits how you want to run it, then a recipe below.

| | One box: a container or a VPS | Vercel and a hosted Postgres |
|---|---|---|
| What runs | one long-lived server process with the board inside, next to Postgres | the board on Vercel's CDN, `/api/*` as one function, Postgres from the Marketplace |
| You look after | the box: its updates, TLS (Caddy in the Compose recipe), disk and backups | nothing but the Vercel project's and the database's settings |
| Scheduled work | every 15 seconds, on the server's own timer | when Vercel Cron calls (daily by default; every minute on Pro with `ANDON_CRON`), and when a machine's heartbeat finds work due |
| Live updates | no platform time limit: a stream ends only when its sign-in token does, and reconnects | streams close before the function's time limit (300 s by default) and reconnect by themselves |
| Voice in the assistant | short-lived tokens, or `VOICE_TRANSPORT=relay` to keep every call on the server | short-lived tokens only: a function can't hold the relay's socket |
| Files | the same volume, or S3 | Vercel Blob, or S3 |
| Cost | the box: a small VPS is enough for a team | Hobby is for personal trials; teams use Pro |

Choose **one box** when you want everything on a machine you control, on a tailnet or behind your own domain, with
no platform limits. Choose **Vercel** when you'd rather run no server at all and a team's board can live on Pro.
Either way you can move later: the database and the files are the whole instance, with `ANDON_SECRET_KEY`.

## Pick a recipe

| Recipe | How | Database | Files | Guide |
|---|---|---|---|---|
| Vercel + Neon | Deploy button | Neon, from the Marketplace | Vercel Blob | [deploy/vercel](https://github.com/psci-labs/andon/blob/main/deploy/vercel/README.md) |
| Vercel + Supabase | Deploy button | Supabase, from the Marketplace | Vercel Blob, or Supabase Storage over S3 | [deploy/vercel](https://github.com/psci-labs/andon/blob/main/deploy/vercel/README.md) |
| Railway | Deploy from GitHub | Railway Postgres | a volume, or S3 | [deploy/railway](https://github.com/psci-labs/andon/blob/main/deploy/railway/README.md) |
| Render | Blueprint (`render.yaml`) | Render Postgres | a disk, or S3 | [deploy/render](https://github.com/psci-labs/andon/blob/main/deploy/render/README.md) |
| Fly.io, one machine | `fly launch` | built in, on the volume | the same volume | [deploy/fly](https://github.com/psci-labs/andon/blob/main/deploy/fly/README.md#one-machine) |
| Fly.io | `fly launch` | Fly Postgres, or any | a volume, or S3 | [deploy/fly](https://github.com/psci-labs/andon/blob/main/deploy/fly/README.md#with-a-separate-database) |
| A VPS | Docker Compose with Caddy | bundled `postgres:17` | a volume | [below](#on-a-fresh-vps) |
| Docker Compose | `docker compose up` | bundled `postgres:17`, or any | a volume, or S3 | [deploy/compose](https://github.com/psci-labs/andon/blob/main/deploy/compose/README.md) |
| Docker, one container | `docker run` | built in, on the volume | the same volume | [below](#one-container-with-its-own-database) |

## The steps every recipe shares

1. **Make a key.** Run `openssl rand -base64 32` and set the result as `ANDON_SECRET_KEY`. It's the only secret you
   provide: sign-in, the encryption of stored secrets and signed file links are all derived from it. Keep it with
   your backups. Without it, a restored database can't read its own stored secrets.
2. **Deploy** with that key and a database URL. Migrations run by themselves: in the production build on Vercel, and
   when the server starts everywhere else.
3. **Open `https://<your host>/setup` straight away**, with the setup token. The server prints it in its log when it
   starts (`setup: open https://<your host>/setup#token=…`: open that link, or paste the token on the page), or set
   your own as `ANDON_SETUP_TOKEN`. Whoever has it creates the owner, who is the instance's admin, and the first org.
   It works once, on a fresh instance. After that it stays closed, even if every org is later deleted.
4. **Add machines.** On each machine that should run cards, run `curl -fsSL https://<your host>/install.sh | sh`, then
   approve it in the browser. **Settings → Machines → Add machine** shows the same line.
5. **Invite people** from the board.

The `use-andon` skill, which lets coding agents outside a run use Andon, comes with the agent, not the server. Each
machine gets it when you add the machine, whichever host you deploy on, Docker included.

## Run the image yourself

The `Dockerfile` at the repository's root builds the server with the built board inside, for `linux/amd64` and
`linux/arm64`. The Compose, Railway, Render and Fly recipes build it themselves. The image:

- migrates the database when it starts
- serves the API and the board on `PORT` (8787)
- keeps files in `/data/storage`, unless `S3_BUCKET` is set
- answers `GET /api/health`

```sh
docker build -t andon-server .
docker run -d --name andon -p 8787:8787 -v andon-data:/data \
  -e ANDON_SECRET_KEY=<your key> \
  -e DATABASE_URL=postgres://<user>:<password>@<host>:5432/andon \
  -e ANDON_URL=https://andon.example.com \
  andon-server
```

Put a TLS proxy in front of it for a public address, and set `ANDON_IP_HEADERS` to the header that proxy sets with
the client's address (`x-forwarded-for` for Caddy), so sign-in rate limits see real clients.

Only a `v*` release tag publishes a prebuilt image, to `ghcr.io/psci-labs/andon-server`, tagged with its version and
`latest`. If there's no release yet, build the image as above.

### One container with its own database

The `single` target is the same image with PostgreSQL 17 inside it. The database lives in `/data/pg` and the files in
`/data/storage`, on one volume. Use it on any host that gives you one container and one volume. The Fly one-machine
recipe uses it too.

1. Build it:

   ```sh
   docker build --target single -t andon-single .
   ```

2. Run it, with no `DATABASE_URL`:

   ```sh
   docker run -d --name andon --restart unless-stopped --stop-timeout 60 \
     -p 8787:8787 -v andon-data:/data \
     -e ANDON_SECRET_KEY=<your key> -e ANDON_URL=https://andon.example.com \
     andon-single
   ```

3. Open `/setup`, with the setup token from `docker logs andon`, and carry on with
   [the shared steps](#the-steps-every-recipe-shares).

At first start the container creates the database on the volume, with a generated password kept in
`/data/.andon-db-password`. Postgres listens inside the container only. On a stop, the server stops first (15 seconds
at most), then Postgres. `--stop-timeout 60` gives both time to stop cleanly: Docker's default of 10 seconds cuts
Postgres off.

If you set `DATABASE_URL` (or any other database URL the server reads) later, the same image leaves its own database
off and uses yours.

To take a dump you can keep elsewhere:

```sh
docker exec andon setpriv --reuid=postgres --regid=postgres --init-groups \
  pg_dump -h /run/postgresql -Fc -f /tmp/andon.dump andon
docker cp andon:/tmp/andon.dump .
```

`bash scripts/fly-single-smoke.sh` builds this image, runs it on a fresh volume, creates the owner, restarts it and
checks the data is still there.

## On a fresh VPS

A single box with a public address, such as an Ubuntu or Debian VPS. This is the Compose recipe with its bundled
database and Caddy for TLS.

1. **Point a domain at it.** Make an `A` (and `AAAA`) record for `andon.example.com` with the VPS's address, and allow
   ports 22, 80 and 443 in its firewall. Caddy needs 80 and 443 to get a Let's Encrypt certificate.
2. **Install Docker and git**, as a user in the `docker` group:

   ```sh
   sudo apt-get update && sudo apt-get install -y git
   curl -fsSL https://get.docker.com | sudo sh
   sudo usermod -aG docker "$USER" && newgrp docker
   ```

3. **Configure** the Compose recipe:

   ```sh
   git clone https://github.com/psci-labs/andon && cd andon/deploy/compose
   cp .env.example .env
   ```

   In `.env`, set `ANDON_HOST=andon.example.com`, `ANDON_SECRET_KEY` to `openssl rand -base64 32`, and
   `POSTGRES_PASSWORD` to `openssl rand -hex 24`.
4. **Start it:** `docker compose --profile db up -d --build`. The first build takes a few minutes. The containers start
   again by themselves after a reboot.
5. **Check it:** `curl -fs https://andon.example.com/api/health` answers `{"ok":true,…}`.
6. **Set up:** open `https://andon.example.com/setup` with the token from
   `docker compose logs server | grep 'setup token'`, then carry on with [the shared steps](#the-steps-every-recipe-shares).

Then [send email](#settings) with `SMTP_URL` in `.env` (and `docker compose up -d`), and [back up](#back-up) the two
volumes with the key. To keep the VPS off the public internet, put it on your tailnet instead:
[On your tailnet](https://github.com/psci-labs/andon/blob/main/deploy/compose/README.md#on-your-tailnet-a-nas-or-home-server).

## Run it from a clone

From a clone, with Node 22 and pnpm 10 and no Docker, `andon up` runs Postgres, the server with the board on
`http://localhost:8787`, and this machine's agent. The data lives in `~/.andon`.

```sh
pnpm install
pnpm andon:up            # start
pnpm andon:up --stop     # stop all three; the data stays
pnpm andon:up --reset    # start again with an empty database
```

The first run builds the board, opens `/setup` in your browser and waits there. Once you've created the owner, it
enrols this machine's agent into the new org and starts it. On this computer `/setup` needs no setup token;
from another device, use the one printed in the server's log. Emails, such as sign-in codes and invites, go to
`~/.andon/mail.log`, and none is sent unless `SMTP_URL` is set in the shell that starts it. On Windows it runs Postgres, the server and the board, but no agent: cards run on a Mac or Linux
machine, or in WSL2 on the same PC ([Windows machines](https://andon-docs.pages.dev/machines/windows.md)).

`andon up` starts its three processes and exits; nothing supervises them. After a crash, a log-out or a reboot, run
`pnpm andon:up` again. For a board that stays up by itself, use one of the recipes above.

| Variable | What it does |
|---|---|
| `ANDON_UP_HOME` | The folder that holds `.andon`, instead of your home folder. |
| `ANDON_UP_PORT` | The port, instead of 8787. |
| `ANDON_UP_TAILNET=off` | Keep it on `localhost`, even when the machine is on a Tailscale network. |

On a tailnet, the board's **Share over HTTPS** (Settings → Machines) gives it `https://<machine>.<tailnet>.ts.net`.
`andon up` then restarts the server on that address. Passkeys work there and on `localhost`, and the links the server
builds itself use the HTTPS address. A link the server hands back to your browser is still built on the address
you're using. Behind your own HTTPS proxy, name its address instead: `pnpm andon:up --url https://andon.example.com`.
The proxy must pass its own host on, as `Host` or `X-Forwarded-Host`, or passkeys may be offered for `localhost`.
Later runs keep that address. `--url auto` goes back to the tailnet address.

To move it to an always-on box later, such as a NAS or a home server on your tailnet, see
[Moving an `andon up` install](https://github.com/psci-labs/andon/blob/main/deploy/compose/README.md#moving-an-andon-up-install-here).

## Host the board somewhere else

The board is a static build. To serve it from its own static host, build it with the server's address and send every
unknown path to `index.html`:

```sh
VITE_ANDON_URL=https://api.example.com pnpm --filter @andon/board build    # into apps/board/dist
```

Then set `ANDON_BOARD_ORIGINS=https://board.example.com` on the server. Cache `assets/` for a year and everything else
with `no-cache`. The repository's `vercel.ts` and `deploy/compose/Caddyfile` show the rules.

## Settings

The server reads everything from its environment. The repository's `.env.example` lists every variable. The ones most
deployments set:

| Variable | What it does |
|---|---|
| `ANDON_URL` | Where Andon is reached. Defaults to the platform's own address on Vercel, Render, Railway and Fly, else `http://localhost:8787`. |
| `DATABASE_URL`, `DATABASE_URL_DIRECT` | The database. Behind a transaction pooler, `DATABASE_URL_DIRECT` is the direct or session-mode URL, for migrations and live updates. |
| `SMTP_URL`, `MAIL_FROM` | Email for invites and sign-in codes. Without them, codes go to the server's log. |
| `ALLOW_SIGNUPS` | Let anyone sign up. Off by default, so people join by invite. Either way they join this instance's org: an instance holds one org, and another org is another instance. |
| `TURNSTILE_SECRET_KEY` | Bot protection: signing up, a password sign-in and every emailed code need a passed Cloudflare Turnstile check. Set it only with a board built with the matching `VITE_TURNSTILE_SITE_KEY`, as Vercel's build does from the project's settings. The Docker image's board is built without one, so leave it unset there, or every password and email-code sign-in fails. |
| `S3_*`, `ANDON_STORAGE` | Files on S3, R2, B2, MinIO or Supabase Storage, instead of the disk or Vercel Blob. |
| `GITHUB_CLIENT_ID`, `GOOGLE_CLIENT_ID`, `APPLE_CLIENT_ID` and their secrets | Sign-in with GitHub, Google or Apple. |
| `GEMINI_API_KEY`, `AI_GATEWAY_API_KEY` | Model calls: the assistant, attention triage, recipe detection, Autopilot, Start work, Auto-Done and voice. `LLM_PROVIDER` picks the default backend. An org can bring its own keys and choose its backend under **Settings → Connections → Advanced** ([AI backends](https://andon-docs.pages.dev/machines/ai-backends.md)). |
| `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` | Web Push notifications. |

## Update

Redeploy the new version. On Docker, build or pull the new image and create the container again from it, because
`docker restart` keeps the old image. Compose does both with `git pull && docker compose --profile db up -d --build`.
Migrations apply by themselves, in order, under a lock, each in its own transaction. Agents update themselves from the
board.

## Back up

Back up the database and the files, and keep `ANDON_SECRET_KEY` with them:

- **Docker Compose,** and **a VPS:** the `pgdata` and `storage` volumes, or your own database.
- **Fly.io, one machine,** and **Docker, one container:** the one volume, or a `pg_dump` as shown in each section.
- **Vercel, Railway and Render:** your database provider's backups, and the Blob store, volume, disk or S3 bucket.

## Change the secret key

Change `ANDON_SECRET_KEY` if it may have leaked. Sign-in sessions and signed file links are derived from the key, so
everyone signs in again afterwards.

1. Make a new key: `openssl rand -base64 32`.
2. Set `ANDON_SECRET_KEY` to the new key and `ANDON_SECRET_KEY_PREVIOUS` to the old one, then redeploy. For several
   old keys, separate them with commas. On Docker, create the container again with the new variables
   (`docker compose up -d`, or `docker stop andon && docker rm andon` and the same `docker run`), because
   `docker restart` keeps the old ones.
3. Run `rotate-secrets` with the server's environment. Pick the line for your host:

   | Host | Command |
   |---|---|
   | Docker Compose | `docker compose exec server node apps/server/src/cli.ts rotate-secrets` |
   | Docker, plain image | `docker exec andon node apps/server/src/cli.ts rotate-secrets` |
   | Docker, one container | `docker exec andon sh -c 'DATABASE_URL="postgres://andon_owner:$(cat /data/.andon-db-password)@127.0.0.1:5432/andon" node apps/server/src/cli.ts rotate-secrets'` |
   | Fly.io | see below the table |
   | Vercel, Railway, Render | from a clone after `pnpm install`: `ANDON_SECRET_KEY=<new> ANDON_SECRET_KEY_PREVIOUS=<old> DATABASE_URL=<the direct URL> node apps/server/src/cli.ts rotate-secrets` |

   On Fly.io, run `fly ssh console`, then in that shell:

   ```sh
   cd /app
   node apps/server/src/cli.ts rotate-secrets                       # with a separate database
   DATABASE_URL="postgres://andon_owner:$(cat /data/.andon-db-password)@127.0.0.1:5432/andon" \
     node apps/server/src/cli.ts rotate-secrets                     # one machine
   ```

   If that shell lacks the server's variables, set them on the command line as in the Vercel row.

   It prints how many secrets it re-encrypted. A secret that neither key opens is left alone and named: add its key
   to `ANDON_SECRET_KEY_PREVIOUS`, or set that secret again on the board.
4. When it says `ANDON_SECRET_KEY_PREVIOUS can go`, remove that variable and redeploy again, the same way.

## Sign the agent builds you publish

The board serves the agent that machines install and update from. Sign it, so a machine can tell an update came from
you:

1. Make an Ed25519 private key in PKCS#8 form and keep it offline.
2. Give it to the board's build only, base64url-encoded, as `ANDON_UPDATE_SIGNING_KEY`. The build signs
   `agent/latest.json` with it.
3. The board's install.sh then pins the matching public key by default. To give a machine the key through a channel
   you trust, separate from the board, install with
   `curl -fsSL https://<your host>/install.sh | sh -s -- --update-key <key>`, or set `ANDON_UPDATE_KEY`.

A board you build without a key serves unsigned agent builds. Its install.sh pins Andon's own release key instead,
and its machines update from Andon's official releases. [Agent updates](https://andon-docs.pages.dev/machines/updates.md) explains what a machine checks.
