Quick start

You need Bun 1.4 or newer and Docker.

Run it

bun install
cp .env.example .env
bun run services:up   # Postgres, Redis and Mailpit in Docker
bun run db:migrate
bun dev               # API, web app and marketing site

What	Where
Web app	http://localhost:5173
API	http://localhost:3000/api/health
Marketing site	http://localhost:4321
Caught email	http://localhost:8025

The mobile app starts on its own, because Expo takes over the terminal: bun run dev:mobile. On a phone, set EXPO_PUBLIC_API_URL to your machine’s address on your network, such as http://192.168.1.20:3000. Sign in with the account you make below. See Mobile app.

Or run everything in Docker

To keep Bun and the apps off your machine, run the API, web app and site in Docker too:

cp .env.example .env
docker compose --profile app up    # or: bun run docker:dev

They run from your files and reload as you edit, at the same addresses as above. The first start installs dependencies into Docker volumes, for Linux, so they never mix with those of a bun install on your machine. Migrations run each time the API starts. Stop everything with docker compose --profile app down.

Run one way or the other: both use the same ports. The mobile app still runs on your machine, with bun run dev:mobile, and reaches the API in Docker at the same address.

Sign up

1. Open http://localhost:5173 and sign up with any address. Nothing leaves your machine.
2. Open Mailpit at http://localhost:8025. Every email the app sends lands there.
3. Follow the link in the verification email. You are signed in.

Emails go out through a background job, so they take a second. If none arrives, check that bun dev is still running.

Make yourself an admin

The admin panel shows everyone who has signed up, and lets you suspend people or sign in as them.

1. Add your address to .env, comma-separated for several: ADMIN_EMAILS=you@example.com
2. Restart bun dev, then reload the app.
3. Open the menu with your name at the foot of the sidebar and choose Admin.

The address must be verified, so nobody can become an admin by signing up with yours. See Admin panel.

Check your work

bun run check

It type-checks, lints, checks formatting and runs every test. Run it before every commit. bun run format fixes formatting.

The tests use their own database (yours with _test on the end) and never call Stripe, Polar, an AI model or an email provider, whatever is in .env.

If a port is taken

Every port is in .env. Some addresses repeat the port, so change them together:

To move	Change	And also
The API	API_PORT	VITE_API_URL, EXPO_PUBLIC_API_URL
The web app	WEB_PORT	WEB_URL, PUBLIC_APP_URL
The site	SITE_PORT	SITE_URL
Postgres	POSTGRES_PORT	DATABASE_URL

After changing a Postgres or Mailpit port, run bun run services:down and bun run services:up.

Next: Make it yours.