Getting Started

Self-Hosting the API

Install, configure, and run the FlagForge Fastify API with SQLite or PostgreSQL

Self-Hosting the API

FlagForge API is a Fastify control plane for managing projects, environments, feature flags, segments, webhooks, and audit logs. Run it in your own environment, connect it to a Prisma-backed database, and expose its REST and OpenAPI interfaces to your operators and applications.

The runtime requires Node.js 20 or newer. The project uses pnpm 8.7.1, so install a compatible pnpm version before running the commands below.

Install and prepare the database

Run these commands from your FlagForge checkout:

Install dependencies

bash

pnpm install

This installs the API and its workspace dependencies and generates the Prisma client through the API package's install lifecycle.

Create the database schema

bash

pnpm --filter @flagforge/api db:setup

The command generates the Prisma client and creates or updates the configured database schema. SQLite is the default backend and uses file:./dev.db when DATABASE_URL is not set. PostgreSQL is supported for production deployments; configure its connection string before setup and review Database Backends for backend-specific deployment guidance.

Optionally load local data

For a local installation that needs an initial project, flags, and API keys, run:

bash

pnpm --filter @flagforge/api db:seed

Keep the server and client keys printed by this command in a secure location. Server keys manage the control plane; client keys are intended for evaluation and SDK bootstrap.

Configure the service

The API reads environment variables at startup. Create a .env file from the supplied .env.example, then set values appropriate for your deployment.

Variable	Default	Purpose
`NODE_ENV`	`development`	Runtime mode. Accepted values are `development`, `test`, and `production`.
`PORT`	`4000`	TCP port on which Fastify listens.
`HOST`	`0.0.0.0`	Bind address.
`LOG_LEVEL`	`info`	Logging verbosity, such as `warn`, `info`, or `debug`.
`DATABASE_URL`	`file:./dev.db`	Prisma database connection URL.
`ADMIN_SERVER_KEY`	`srv_dev_admin_key_change_me`	Server key used for administrative access when no other value is configured. Replace the development default before exposing the API.

Note:

Do not use the default ADMIN_SERVER_KEY in a shared or production deployment. Store administrator credentials in your deployment secret manager and send them only as Bearer tokens over HTTPS.

The default listener is 0.0.0.0:4000. With the default local configuration, the service is available at http://localhost:4000.

Start the API

Development

Use the development command while configuring or operating a local instance:

bash

pnpm --filter @flagforge/api dev

The command watches the API source and starts the Fastify server. The process logs the listening address and the OpenAPI UI address when startup succeeds.

Production

Build the API, then start the compiled server:

bash

pnpm --filter @flagforge/api build
node apps/api/dist/server.js

The API package also exposes a start script. When your deployment runs commands from the API package directory, the equivalent is:

bash

pnpm --filter @flagforge/api start

Ensure the database schema has been prepared and production environment variables are available to the process before starting it. Fastify exits with an error if it cannot bind the configured host and port.

Verify liveness and discover the API

The unauthenticated health endpoint checks both the API process and database connectivity:

bash

curl http://localhost:4000/health

A healthy instance returns HTTP 200 with a response shaped like:

json

{"status":"ok","uptime":12.34}

If the process is running but the database cannot be reached, the endpoint returns HTTP 503 with status set to degraded and an error message. Use this endpoint as the liveness or readiness check for your process manager and deployment platform.

After the health check succeeds, open http://localhost:4000/docs for the interactive Swagger UI or fetch http://localhost:4000/openapi.json for the generated OpenAPI document. See OpenAPI Discovery for ways to use the live contract.

Use server API keys with management endpoints and client API keys with evaluation endpoints. Send either as a Bearer token:

bash

curl -H "Authorization: Bearer <server-key>" \
  http://localhost:4000/v1/projects

For the SDK, configure the client key, the service base URL, and an environment, then call init() to bootstrap from /v1/config. Continue with the SDK Client Guide once the API is healthy.

Next steps

Configure the deployment

Review runtime settings such as host, port, logging, database connectivity, and administrator credentials.

Manage resources

Create projects and environments before defining flags and targeting rules.

Use the REST API

Explore authentication, management resources, evaluation endpoints, and request schemas.

PreviousQuickstart NextConfiguration