Configuration

Use this page to understand the environment variables and local state files that control a LicenseKit deployment.

Who This Is For

• operators configuring local, self-hosted, or Cloud Run deployments
• developers debugging environment precedence
• teams enabling Google sign-in, CORS, or PDF rendering

When To Use This

Read this before deploying or when behavior differs between local and hosted environments.

How It Works

LicenseKit loads configuration from:

1. default values
2. .locksmith/locksmith.env or the configured state dir equivalent
3. environment variables
4. CLI flag overrides

Important environment variables:

Variable	Purpose
LOCKSMITH_ADDR	HTTP listen address
LOCKSMITH_STATE_DIR	local state directory
LOCKSMITH_KEYSET_PATH	signing keyset JSON path
LOCKSMITH_BOOTSTRAP_PATH	bootstrap record JSON path
LOCKSMITH_DB_URL	PostgreSQL connection string
LOCKSMITH_GOOGLE_CLIENT_IDS	comma-separated Google web client IDs
LOCKSMITH_ALLOWED_ORIGINS	comma-separated allowed browser origins
LOCKSMITH_TYPST_BIN	Typst binary path for PDF export rendering

Defaults worth knowing:

• default listen address: :8080
• default state dir: .locksmith
• default keyset path: .locksmith/signing-keyset.json
• default bootstrap path: .locksmith/bootstrap.json

locksmith init generates a local env file automatically for the local state directory.

Example

Typical local env file contents:

LOCKSMITH_ADDR=:8080
LOCKSMITH_STATE_DIR=.locksmith
LOCKSMITH_KEYSET_PATH=.locksmith/signing-keyset.json
LOCKSMITH_BOOTSTRAP_PATH=.locksmith/bootstrap.json
LOCKSMITH_DB_URL=postgres://locksmith:locksmith@localhost:5432/locksmith?sslmode=disable

Hosted deployment additions:

LOCKSMITH_GOOGLE_CLIENT_IDS=your-client-id.apps.googleusercontent.com
LOCKSMITH_ALLOWED_ORIGINS=https://app.licensekit.dev,http://localhost:3000
LOCKSMITH_TYPST_BIN=/usr/local/bin/typst

Common Mistakes

• assuming CLI flags and env vars are merged without precedence rules
• mounting the keyset but forgetting to set LOCKSMITH_KEYSET_PATH
• forgetting LOCKSMITH_TYPST_BIN or typst on PATH when self-hosting PDF exports
• treating .locksmith contents as non-sensitive

Related Pages

• Self-Hosting
• Cloud Run
• PDF Exports