Flag Controller is an open-source feature flag management platform built on OpenFeature. It lets teams turn functionality on or off without changing source code or redeploying. See the documentation for concepts, architecture, and usage.
This Turborepo includes the following apps:
api: a Fastify server using TypeScript, and Drizzle ORM for database access to a Postgres databasedocs: comprehensive documentation built with Docusaurus explaining architecture and usageui: a Next.js app built with React, Tailwind CSS, and Carbon UI for a modern, accessible interface
libs/shared-constants: constants shared across all applicationslibs/shared-types: TypeScript type definitions and interfaces shared across all applicationslibs/shared-utils: utility functions shared across all applications
- Node.js, according to the
.nvmrcfile at the root of the repository. - pnpm (the repo pins its version in
package.json; runcorepack enable pnpmto use it automatically) - Docker (optional — used to run the whole stack together, see Docker)
- A local PostgreSQL database when running the API outside of Docker (see Database)
-
Install all dependencies from the repo root:
pnpm install
-
Create the environment files each app needs by copying the provided examples:
cp apps/api/.env.example apps/api/.env cp apps/ui/.env.example apps/ui/.env
Review each
.envand fill in the required values. Every setting is documented inline in the example files, and the API README lists the variables the API requires.Sign-in is configured with
AUTH_PROVIDER. GitHub is the only option today, and the setting is designed to take more providers, such as OpenID Connect identity providers, as they are added.
Run pnpm schema:sync at the repo root to refresh the committed flagd schema JSON files and the generated shared TypeScript types.
Run pnpm schema:check to verify those generated artifacts are already in sync. CI uses the same check to catch drift.
Behind a TLS-inspecting proxy?
schema:syncfetches the schema over HTTPS fromhttps://flagd.dev. Proxies that inspect TLS re-sign responses with their own certificate authority, which Node.js does not trust by default, so the fetch fails with an error such asUNABLE_TO_VERIFY_LEAF_SIGNATUREorSELF_SIGNED_CERT_IN_CHAIN.Point Node.js at the CA bundle your proxy uses. Ask whoever administers it where to find the file:
NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem pnpm schema:syncAs a local-development-only last resort, you can disable certificate verification entirely:
NODE_TLS_REJECT_UNAUTHORIZED=0 pnpm schema:sync
⚠️ Never useNODE_TLS_REJECT_UNAUTHORIZED=0in production or CI — it disables all TLS verification and exposes you to man-in-the-middle attacks.
We format and lint code using Biome. For the best development experience, download the Biome extension for your IDE and make sure that if you have other formatters or linters like Prettier or ESLint that they are disabled for this workspace.
See the UI README for how to run the UI development server.
See the API README for how to run the API development server.
The API needs a local Postgres database. See the API README for how to set up the database, configure DATABASE_URL, and run migrations.
We are using docker compose to be able to run the different parts of the system together more easily. While this is a nice to have, you can run the API and UI separately locally and achieve a similar development result.
You can run production builds all of the applications together using docker compose:
docker compose up -d --buildYou can also use compose to just run a specific service:
docker compose up -d --build apiTip
If your docker build is behaving strangely, try building with the --no-cache option
# Build everything with no cache
docker compose build --no-cache && docker compose up -d
# Build a specific service with no cache
docker compose build --no-cache docs && docker compose up -d docs