Getting Started

Get Pluma running locally with Docker Compose and evaluate your first feature flag with the SDK.

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:v1.3.0
    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:v1.3.0
    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

Environment variables

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.

Install the SDK


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

Create an SDK token

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

Basic usage


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
}

See the SDK documentation for framework examples, per-subject targeting, caching behaviour, and the complete API reference.