Quickstart

Run from Docker image in a few minutes

1) Pull the image

bash

docker pull bytebardorg/simplelicenseserver

2) Create docker-compose.yml (full settings example)

Save this as docker-compose.yml. The comments call out which API environment variables are required and which are optional.

yaml

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: simple_license_server
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d simple_license_server"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data
    # Optional: expose Postgres to your host for debugging.
    # ports:
    #   - "5432:5432"

  api:
    image: bytebardorg/simplelicenseserver
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      # REQUIRED: database connection used by the API service.
      DATABASE_URL: postgres://postgres:postgres@postgres:5432/simple_license_server?sslmode=disable

      # REQUIRED: management bootstrap key (16+ chars). You can also use MANAGEMENT_API_KEY.
      MANAGEMENT_API_KEYS: management_key_dev_123456

      # OPTIONAL: API listen port (default: 8080).
      PORT: "8080"

      # OPTIONAL: request and server shutdown controls.
      REQUEST_TIMEOUT: 15s
      SHUTDOWN_TIMEOUT: 10s
      HTTP_READ_TIMEOUT: 15s
      HTTP_WRITE_TIMEOUT: 30s
      HTTP_IDLE_TIMEOUT: 60s

      # OPTIONAL: global and per-IP rate limiting.
      RATE_LIMIT_ENABLED: "true"
      RATE_LIMIT_GLOBAL_RPS: "100"
      RATE_LIMIT_GLOBAL_BURST: "200"
      RATE_LIMIT_PER_IP_RPS: "20"
      RATE_LIMIT_PER_IP_BURST: "40"
      RATE_LIMIT_IP_TTL: 10m
      RATE_LIMIT_MAX_IP_ENTRIES: "10000"

      # OPTIONAL: set true only when a trusted proxy sets forwarding headers.
      TRUST_PROXY_HEADERS: "false"

volumes:
  postgres_data:

3) Start the stack

bash

docker compose up -d

4) Verify health

bash

curl -sS http://localhost:8080/healthz

5) Create your first generated server API key

bash

curl -sS http://localhost:8080/management/api-keys \
  -H "Authorization: Bearer management_key_dev_123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"quickstart"}'

6) Generate your first license key

bash

curl -sS http://localhost:8080/generate \
  -H "Authorization: Bearer <generated_server_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_quickstart_001" \
  -d '{"slug":"default","metadata":{"email":"user@example.com","source":"quickstart"}}'