Self-hosted feature flag system. Manage flags via a web UI and evaluate them in your application with a lightweight SDK.

Pluma (Spanish: feather) — lightweight by design.

---

Quick start

Docker Compose

Pluma ships as pre-built Docker images. No build step required.

1. Create a docker-compose.yml:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: ${DB_USER:-pluma}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-pluma}
      POSTGRES_DB: ${DB_NAME:-pluma}
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test:
        ["CMD-SHELL", "pg_isready -U ${DB_USER:-pluma} -d ${DB_NAME:-pluma}"]
      interval: 5s
      timeout: 5s
      retries: 10

  api:
    image: ghcr.io/403-html/pluma-api:latest
    ports:
      - "2137:2137"
    environment:
      DATABASE_URL: postgresql://${DB_USER:-pluma}:${DB_PASSWORD:-pluma}@db:5432/${DB_NAME:-pluma}?schema=public
    depends_on:
      db:
        condition: service_healthy

  app:
    image: ghcr.io/403-html/pluma-app:latest
    ports:
      - "3000:3000"
    environment:
      API_URL: ${API_URL:-http://api:2137}
    depends_on:
      - api

volumes:
  db_data:

2. Start the stack:

docker compose up -d

• UI → http://localhost:3000
• API → http://localhost:2137

Variable	Default	Description
DB_USER	pluma	PostgreSQL username
DB_PASSWORD	pluma	PostgreSQL password
DB_NAME	pluma	PostgreSQL database name
API_URL	http://api:2137	API base URL

First run: change DB_PASSWORD to a strong value before going to production.

SDK

npm install @pluma-flags/sdk
# or
pnpm add @pluma-flags/sdk

SDK tokens are created in the Pluma UI under Organisation → API Keys. Each token is scoped to a project and environment.

import { PlumaSnapshotCache } from "@pluma-flags/sdk";

const client = PlumaSnapshotCache.create({
  baseUrl: "http://localhost:2137",
  token: "sdk_your_token_here", // Organisation → API Keys in the Pluma UI
  ttlMs: 30_000, // optional; defaults to 30_000 ms (30 s)
});

const evaluator = await client.evaluator({ subjectKey: "user-123" });

if (evaluator.isEnabled("my-feature-flag")) {
  // feature is enabled for this subject
}

For the full SDK reference (caching, per-subject targeting, framework examples, and the complete API) see packages/sdk/README.md.

Scaling

The api service is stateless and can be scaled horizontally by running multiple replicas behind an nginx reverse proxy. See SCALING.md for a step-by-step guide.

Contributing

See CONTRIBUTING.md for dev setup and contribution guidelines.

Support

If Pluma is useful to you, consider buying a coffee ☕.

License

Apache 2.0, see LICENSE.