Self-Hosting

Use this page to run LicenseKit yourself with PostgreSQL and the locksmith CLI.

Who This Is For

• teams evaluating or operating a self-hosted deployment
• developers running LicenseKit locally
• operators who want direct control of state and infrastructure

When To Use This

Use self-hosting when the hosted API is not the target deployment model.

How It Works

The basic local or self-hosted flow is:

1. start PostgreSQL
2. build the locksmith binary
3. run locksmith init
4. run locksmith migrate up
5. run locksmith serve

The repo also includes:

• Dockerfile
• docker-compose.yml

The compose file starts:

• db on PostgreSQL 16
• app with serve --addr :8080 --state-dir /data

Example

Local CLI path:

docker compose up -d db
make build
./bin/locksmith init
./bin/locksmith migrate up
./bin/locksmith serve

Docker Compose path:

docker compose up --build

Important generated local state from locksmith init:

• signing keyset JSON
• bootstrap record JSON
• .locksmith/locksmith.env
• initial admin API key, shown once

Common Mistakes

• running serve before applying migrations
• losing the one-time bootstrap admin key output from init
• treating local .locksmith state as disposable when it contains active signing material
• forgetting that the service still needs a PostgreSQL connection string

Related Pages

• Configuration
• Health And Readiness
• Key Rotation