Running Locally

For the full server/UI stack:

task up

This starts the API server, management UI, API documentation, and PostgreSQL. The API is available at http://localhost:8080, the UI at http://localhost:3000.

On first run, task up copies deploy/.env.example to deploy/.env with safe local defaults (including AILERON_JWT_SIGNING_KEY). No manual setup needed.

Email verification is disabled by default locally (AILERON_AUTO_VERIFY_EMAIL=true), so new accounts are activated immediately after signup.

Customizing the local environment

Edit deploy/.env (gitignored) to customize. For example, to enable OAuth providers locally:

# deploy/.env
AILERON_JWT_SIGNING_KEY=local-dev-signing-key-not-for-production
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_OAUTH_CLIENT_ID=your-github-client-id
GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret

Verification codes for email/password signup are printed to the server log when RESEND_API_KEY is not set (dev mode). To send real emails, add RESEND_API_KEY (and optionally MAIL_FROM) to your .env.

Stopping

task down

Auth environment variables

Docker Compose connects to PostgreSQL, which enables auth and requires a JWT signing key. Locally, task up handles this automatically. In CI, the workflow sets its own values directly. For other environments, create deploy/.env with at minimum:

AILERON_JWT_SIGNING_KEY=<any 32+ character string>