Configuration

Ablebase is configured through environment variables. The API reads variables from packages/api/.env.

For the full reference, see Environment Variables.

Minimum required configuration

Create packages/api/.env with at least these variables before starting:

DATABASE_URL=postgresql://user:password@localhost:5432/ablebase
BETTER_AUTH_SECRET=<output of: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:5173
ALLOW_SIGNUP=true
RESEND_API_KEY=re_xxxxxxxx
EMAIL_FROM="Ablebase <noreply@example.com>"

New accounts must verify their email address before they can sign in, so Ablebase needs a Resend API key and a sender address on a domain verified in Resend. Without them, no verification emails are sent.

BETTER_AUTH_URL must be the web origin (not the API’s own port), because authentication callbacks and session cookies are set against the web domain.

Enabling sign-up

By default, new account registration is blocked. Set ALLOW_SIGNUP=true to open self-service registration. Once you have created the initial admin account you can set it back to false.

GitHub OAuth

To allow users to sign in with GitHub, create a GitHub OAuth App and provide its credentials:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

The callback URL for the GitHub OAuth App must be:

<BETTER_AUTH_URL>/api/auth/callback/github

Caution

GitHub OAuth can only sign in to existing accounts. It cannot create new accounts on its own — the user must first register with email and password.

GitHub App (integrations)

The Integrations feature — linking repositories and importing issues — uses a dedicated GitHub App, separate from the GitHub OAuth sign-in above. Register a GitHub App and provide its credentials:

GITHUB_APP_ID=your_app_id
GITHUB_APP_PRIVATE_KEY=your_private_key_pem   # encode newlines as \n
GITHUB_APP_CLIENT_ID=your_client_id
GITHUB_APP_CLIENT_SECRET=your_client_secret
GITHUB_APP_WEBHOOK_SECRET=your_webhook_secret
GITHUB_APP_SLUG=your-app-slug

The integration is enabled only when all of these are set; if any is missing, GitHub integration is disabled and the app still boots.

When registering the App:

• Permissions: Issues (Read & write), Metadata (Read).

• Webhook URL: point it at the API’s webhook receiver so linked issues sync in near-real-time:

  <host>/api/integrations/github/webhooks

• Webhook secret: set the same value as GITHUB_APP_WEBHOOK_SECRET. Ablebase verifies every inbound webhook against this secret; without it, webhooks are inert and import falls back to manual Sync now.

• Subscribe to events: Issues, Installation, and Installation repositories.

Note

Behaviour, per-repository configuration, and the user-facing setup flow are documented under Integrations.

File uploads

Profile pictures, organization logos, and cached integration logos are stored on the local filesystem. In containerized deployments, mount a persistent volume at the path specified by UPLOAD_DIR (default: ./uploads):

UPLOAD_DIR=/data/uploads

Behind a reverse proxy

If Ablebase runs behind a reverse proxy (e.g. Nginx, Caddy), set TRUST_PROXY=true so that rate limiting uses the client’s real IP address rather than the proxy’s IP.

By default the client IP is read from X-Forwarded-For, assuming one proxy in front of the API. If your proxy sends X-Real-IP instead, set CLIENT_IP_HEADER=x-real-ip. If there is more than one proxy, set TRUSTED_PROXY_HOPS to the number of proxies.