Skip to main content

1. Quick Start (Dev)

This starts PostgreSQL, Redis, and the auth service. Two developer accounts are seeded automatically: Verify it’s running:
The dev compose exposes database and Redis ports and uses hardcoded credentials. Never use it in production.

2. Generating a Production RSA Key

Grantex signs grant tokens with RSA-256. Generate a 2048-bit private key:
Collapse to a single line for environment variables:
Copy the output and use it as RSA_PRIVATE_KEY.
Keep private.pem out of source control. The JWKS endpoint exposes only the public key.

3. Production Docker Compose

Prerequisites

  • Docker 24+ with Compose v2
  • A domain name with DNS pointing to your server
  • TLS certificate (Let’s Encrypt for production)

Step 1 — Fill in the env file

Edit .env.prod and replace every change-me-* placeholder. Set RSA_PRIVATE_KEY to the collapsed PEM and JWT_ISSUER to your public base URL.

Step 2 — Provide TLS certificates

Step 3 — Start the stack

Architecture:

4. Kubernetes / Helm

Prerequisites

  • Kubernetes 1.26+, Helm 3.x
  • Managed PostgreSQL and Redis
  • An RSA private key (Section 2)

Install

Enable Ingress

Use an existing Secret

5. Environment Variable Reference

This table is a quick-start subset, not an exhaustive schema. Consult apps/auth-service/src/config.ts and .env.example from the exact release you deploy for all feature-specific settings and validation rules.

6. Database Migrations

Migrations run automatically on every startup. The auth service reads all *.sql files from the migrations/ directory and executes each one using idempotent DDL (CREATE TABLE IF NOT EXISTS, etc.). The repository currently contains ordered migrations through 063, covering core authorization, webhooks, policy, enterprise identity, credentials, budgets, offline operation, trust registry, DPDP, commerce, and MCP certification-state integrity. Inspect the migration directory in the exact release you deploy rather than relying on a copied file count. To upgrade, just restart the service — new migration files are applied automatically.

7. Key Rotation

  1. Generate a new RSA key pair (Section 2)
  2. Update RSA_PRIVATE_KEY in your env file or Kubernetes secret
  3. Restart the auth service
The bundled JWKS endpoint publishes the active signing key. Replacing that key without also publishing the previous public key makes previously issued tokens fail signature verification. Schedule signing-key rotation after old tokens expire (or implement an overlapping multi-key JWKS) and test verifiers before removing the old key.

8. Health Checks & Monitoring

All logs are emitted as JSON to stdout, compatible with Datadog, Loki, and CloudWatch Logs.

9. Backup & Recovery

PostgreSQL

Redis

Redis holds ephemeral token metadata and rate-limiting state. If Redis data is lost, in-flight auth requests will fail temporarily, but no permanent data is lost. PostgreSQL is the source of truth.

10. Production Readiness Checklist

  • RSA_PRIVATE_KEY is a real 2048-bit RSA key
  • POSTGRES_PASSWORD and REDIS_PASSWORD are strong random values
  • SEED_API_KEY and SEED_SANDBOX_KEY are not set
  • TLS is enabled end-to-end
  • Database and Redis ports are not exposed publicly
  • JWT_ISSUER matches your public base URL exactly
  • Automated database backups are configured
  • Health checks are wired into your load balancer
  • CPU and memory limits are set
  • Log forwarding is configured
Last modified on July 11, 2026