FlagPulse

Appearance

Getting Started ​

FlagPulse ships as four Docker services orchestrated with Docker Compose: Postgres, Redis, the backend API, and Nginx (which serves the built React dashboard and reverse-proxies /api/).

Prerequisites ​

  • Docker and Docker Compose
  • Nothing else — the backend runs its own migrations on startup

1. Clone and configure ​

bash
git clone https://github.com/hitheshn288/flagpulse.git
cd flagpulse
cp .env.example .env

Fill in .env:

bash
# Postgres Database
DB_USER=
DB_PASSWORD=
DB_NAME=

# JWT
JWT_SECRET=

# Port to expose the FlagPulse dashboard/API on
PORT=

See Environment Variables for details on each value.

2. Start the stack ​

bash
docker compose up --build

This brings up, in order:

  1. postgres — waits until pg_isready passes before anything else starts
  2. redis — used for flag/SDK-key caching and the CORS origin allowlist
  3. backend — runs npm run migrate (applying any pending SQL files in backend/db/migrations) and then npm run start
  4. nginx — built from the frontend/ Dockerfile, serves the compiled dashboard and proxies /api/ to the backend on port 3000

The dashboard is available at http://localhost:${PORT}.

3. Create your account and first project ​

  1. Open the dashboard and register a user (POST /api/auth/register under the hood).
  2. Create a project — this also creates its first environment (name, icon, and the origin URL that will be allowed to call the SDK/SSE endpoints from a browser).
  3. Create a flag on the project. A flag is created once per project and gets a flag_values row per environment, each independently toggleable.
  4. Copy the environment's SDK key from the dashboard and use it from your application — see SDK Quickstart.

Local (non-Docker) development ​

If you'd rather run the pieces individually:

bash
# Backend
cd backend
npm install
npm run migrate   # applies backend/db/migrations against your own Postgres
npm run start      # listens on 0.0.0.0:3000

# Frontend
cd frontend
npm install
npm run dev         # Vite dev server, proxies API calls per vite.config.ts

You'll need your own Postgres and Redis reachable at the hosts configured in backend/config/postgres.js (postgres) and backend/config/redis.js (redis://redis:6379) — when running outside Docker Compose, update those hosts or run Postgres/Redis containers on the same names/network.

Next: deploying for real ​

The walkthrough above is enough to try FlagPulse locally. For a full breakdown of each Docker service, volumes, and how migrations run — see Docker Compose deployment, then Environment Variables.

Once your server is up and you have an SDK key, jump to Using the React SDK to start reading flags from your app.