Configuration

Ablebase is configured through environment variables. The API reads variables from packages/api/.env; the web app reads variables prefixed with VITE_ at build time.

For the full reference, see Environment Variables.

Minimum required configuration

Create packages/api/.env with at least these four 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

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.

File uploads

Profile pictures and organization 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, Railway), set TRUST_PROXY=true so that rate limiting uses the client’s real IP address rather than the proxy’s IP.

Feature flags (Flagsmith)

Ablebase supports Flagsmith for feature flags. Both keys are optional — if omitted, all flags return their default values:

# API (server-side, keep secret)
FLAGSMITH_ENVIRONMENT_KEY=ser.xxxxxxxx

# Web (client-side, safe to expose)
VITE_FLAGSMITH_ENVIRONMENT_ID=xxxxxxxx

Error tracking (Sentry)

Set SENTRY_DSN in the API environment to enable Sentry error tracking:

SENTRY_DSN=https://xxxxxxxx@o0.ingest.sentry.io/0

Railway deployments

On Railway, the RAILWAY_SERVICE__ABLEBASE_WEB_URL variable is injected automatically. Ablebase uses this to allow the web service’s public domain as a trusted CORS and auth origin without additional configuration.