Cloud Run

Use this page to run LicenseKit on Google Cloud Run with a separate migration job and service deployment.

Who This Is For

• operators deploying LicenseKit on Google Cloud Run
• teams using Secret Manager for runtime secrets
• developers preparing a managed self-hosted deployment path

When To Use This

Use Cloud Run when you want a managed container deployment on Google Cloud.

How It Works

Current deployment model:

1. build one container image
2. run a Cloud Run Job for locksmith migrate up
3. run a Cloud Run Service for locksmith serve

Important runtime inputs:

• LOCKSMITH_DB_URL
• signing keyset JSON

Common optional inputs:

• bootstrap record JSON
• LOCKSMITH_GOOGLE_CLIENT_IDS
• LOCKSMITH_ALLOWED_ORIGINS
• LOCKSMITH_KEYSET_PATH

Hosted probe note:

• prefer /health for external liveness on Cloud Run
• keep /healthz for local and self-hosted compatibility

Example

Build and push:

export PROJECT_ID="your-project-id"
export REGION="us-central1"
export REPOSITORY="licensekit"
export IMAGE="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/locksmith:$(git rev-parse --short HEAD)"

gcloud builds submit --tag "$IMAGE"

Deploy the migration job:

gcloud run jobs deploy locksmith-migrate \
  --image "$IMAGE" \
  --region "$REGION" \
  --command /usr/local/bin/locksmith \
  --args migrate,up \
  --tasks 1 \
  --max-retries 0 \
  --set-secrets LOCKSMITH_DB_URL=locksmith-db-url:latest

Deploy the service:

gcloud run deploy locksmith \
  --image "$IMAGE" \
  --region "$REGION" \
  --allow-unauthenticated \
  --port 8080 \
  --set-secrets LOCKSMITH_DB_URL=locksmith-db-url:latest,/var/run/licensekit/signing-keyset.json=locksmith-signing-keyset:latest \
  --set-env-vars LOCKSMITH_KEYSET_PATH=/var/run/licensekit/signing-keyset.json

Common Mistakes

• skipping the migration job before a schema-changing rollout
• assuming /healthz is the best external Cloud Run probe path
• baking signing material into the image instead of mounting it from secrets
• describing the Cloud Run setup as production-hardened without soak, alerting, and rollback practice

Related Pages

• Self-Hosting
• Configuration
• Health And Readiness