Install Open Spanner

Docker Compose is the quickest supported installation. It starts the dashboard, API, Postgres, and every worker with the required private networking and shared storage.

Start The Product

git clone https://github.com/ssubedir/open-spanner.git
cd open-spanner
docker compose -f docker-compose.app.yml up -d --build

Open http://localhost:18081/register, create an account, and then create an API key from API Keys. Copy the key immediately; Open Spanner does not display the full secret again.

The public endpoints are:

The API, Postgres, metrics, and worker probes remain private to the Compose network. For production topology and published images, see Production Deployment.

Record The First Event

Create a meter from the dashboard or API:

export BASE_URL="http://localhost:18081"
export API_KEY="osp_..."

curl -X POST "$BASE_URL/v1/meters" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_requests",
    "description": "API requests served",
    "unit": "request",
    "aggregation": "sum",
    "event_retention_days": 90
  }'

Then send usage from trusted backend code:

curl -X POST "$BASE_URL/v1/usages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "org_123",
    "meter": "api_requests",
    "quantity": 1,
    "idempotency_key": "usage_001",
    "metadata": {
      "region": "us-east",
      "plan": "pro"
    }
  }'

Use a stable, unique idempotency key for each product action so retries cannot double-count usage.

Run From Source

Install Task, then start the API and dashboard in separate terminals:

task run:sqlite
task control-plane:dev

Start workers separately when testing queued or asynchronous behavior:

task run:usage-worker
task run:export-worker
task run:alert-worker
task run:entitlement-worker

Use task postgres:up followed by the corresponding *:postgres tasks when testing a production-like Postgres setup.

Next Steps

• Query the recorded usage.
• Choose an SDK for Go, TypeScript, Python, or C#.
• Define dimensions for filtering and grouping.
• Create plans and enforce quota.

Stop the local stack with docker compose -f docker-compose.app.yml down. Add -v only when you also want to delete the Postgres data volume.