Configuration

Configuration

FlagForge API configuration is supplied through environment variables. The API reads the process environment when its configuration is loaded and validates the values before the application starts. Configure these variables in the environment of the process that runs the API; an environment file is also suitable when your process manager or shell loads it.

The defaults support a local development instance: the API listens on port 4000, binds to all interfaces, logs at info, and uses a SQLite database at file:./dev.db. For production, set an explicit database URL, bind address, log level, and secret values rather than relying on development defaults.

Configuration options

Invalid values fail configuration parsing at startup. In particular, NODE_ENV must be one of the three listed values, PORT must be a positive integer, and LOG_LEVEL must be one of the listed logger levels.

Environment variables

Set the variables in the API process environment. The following shell example uses the defaults for the listener while replacing the database and secret values:

export NODE_ENV=production
export PORT=4000
export HOST=0.0.0.0
export LOG_LEVEL=info
export DATABASE_URL='file:./prod.db'
export ADMIN_SERVER_KEY='replace-with-a-long-random-server-key'

HOST controls where Fastify accepts connections. Use 127.0.0.1 when the API should only be reachable locally, or 0.0.0.0 when a reverse proxy, container network, or other host must reach it. PORT must be available on that host; if a proxy is in front of FlagForge, forward traffic to the configured host and port.

LOG_LEVEL controls the Fastify logger. Use warn or error to reduce routine output, and use debug or trace temporarily when diagnosing a deployment. silent disables logger output.

DATABASE_URL is consumed by Prisma. The shipped schema defaults to SQLite, so file:./dev.db is the zero-setup choice. PostgreSQL deployments require configuring the Prisma datasource for PostgreSQL as well as supplying a PostgreSQL connection URL; changing only DATABASE_URL does not change the datasource provider.

Example configuration file

The API configuration reads environment variables rather than a custom FlagForge configuration object. Save the following as an environment file only when your chosen launcher loads it:

# Runtime mode: development, test, or production.
NODE_ENV=production

# Fastify listener.
PORT=4000
HOST=0.0.0.0

# fatal, error, warn, info, debug, trace, or silent.
LOG_LEVEL=info

# SQLite example. For PostgreSQL, use a PostgreSQL URL and configure the datasource provider.
DATABASE_URL=file:./prod.db

# Replace this value before deploying.
ADMIN_SERVER_KEY=replace-with-a-long-random-server-key

For example, a shell can load the file before starting the development server:

set -a
. ./.env
set +a
pnpm --filter @flagforge/api dev

Do not publish this file if it contains a server key or database credentials.

Common setups

Minimal local setup

Use the built-in defaults for a local SQLite instance:

pnpm install
pnpm --filter @flagforge/api db:setup
pnpm --filter @flagforge/api dev

The API is available at http://localhost:4000. Confirm it is running with http://localhost:4000/health; the OpenAPI UI is at http://localhost:4000/docs.

Local API on one machine

Bind only to the loopback interface when other machines or containers do not need access:

NODE_ENV=development
HOST=127.0.0.1
PORT=4000
LOG_LEVEL=debug
DATABASE_URL=file:./dev.db
ADMIN_SERVER_KEY=replace-for-local-use

This keeps the listener local while allowing more verbose diagnostics during development.

Production behind a proxy

Use an explicit secret and database URL, and let the proxy expose the public address:

NODE_ENV=production
HOST=0.0.0.0
PORT=4000
LOG_LEVEL=info
DATABASE_URL=postgresql://flagforge:password@db.example.internal:5432/flagforge
ADMIN_SERVER_KEY=replace-with-a-secret-from-your-secret-store

After applying the environment, run the database setup required by your deployment, start the built API with node dist/server.js, and probe /health. Use a server API key for management endpoints and a project-scoped client API key for SDK bootstrap and evaluation. See Authentication and OpenAPI Discovery for request credentials and live contract details.

Administrative key and API authentication

ADMIN_SERVER_KEY is part of the validated API environment, but API request authentication resolves Bearer tokens against API keys stored in the database. Changing this environment variable should not be treated as rotating an existing database API key. Send the applicable key in the request header:

Authorization: Bearer <api-key>

Use server keys for control-plane operations such as projects, environments, flags, and segments. Use client keys for application evaluation and SDK bootstrap. If authentication fails after configuration changes, check the key type, project scope, and Authorization header before troubleshooting the listener.