Local Dev Setup

:::info Source Sourced from services/certification-service/LOCAL_DEV_SETUP.md in the documentation repo. :::

1. Prerequisites

Node 20, pnpm 9, Docker 24, Chromium (for renderer, auto-installed via Puppeteer).

2. Quick Start

cd services/certification-service
cp .env.example .env.local
pnpm install
docker compose -f docker-compose.dev.yml up -d
pnpm db:migrate
pnpm kms:init                # generate tenant signing keys in localstack
pnpm seed
pnpm dev                     # :3100
pnpm dev:issuer
pnpm dev:renderer

3. Dependencies

Service	Port
postgres	5432
redis	6379
nats	4222
minio	9000
localstack (KMS)	4566
progress-service (mock)	3030
media-service (mock)	3060 (for logos)

4. Environment

PORT=3100
DATABASE_URL=postgres://cert:cert@localhost:5432/cert
REDIS_URL=redis://localhost:6379/100
NATS_URL=nats://localhost:4222
NATS_STREAM=CERTIFICATION
S3_ENDPOINT=http://localhost:9000
S3_BUCKET_ARTIFACTS=cert-artifacts-dev
KMS_ENDPOINT=http://localhost:4566
KMS_KEY_ALIAS_PREFIX=alias/ghasi-cert-signer-

VERIFY_TOKEN_HMAC_SECRET_KMS=alias/ghasi-cert-verify-hmac
VERIFY_RATE_LIMIT_IP=60
VERIFY_RATE_LIMIT_TENANT=10000
VERIFY_CDN_CACHE_SECONDS=60

RENDER_CHROME_ARGS="--no-sandbox,--disable-gpu"
OPEN_BADGES_ISSUER_URL=http://localhost:3100/api/v1/.well-known/certification-keys.json

5. Seed Data

• 3 certificate templates (simple, corporate, academic).
• 5 issued certificates for seeded users in 2 tenants.
• 1 offline-claim fixture (used in E2E).
• 1 revoked certificate.

6. Commands

pnpm dev
pnpm test
pnpm test:integration
pnpm test:openbadges        # OpenBadges conformance
pnpm test:jws:roundtrip
pnpm verify:token <token>
pnpm render:preview <templateId> <sampleJson>
pnpm kid:rotate              # triggers kid rotation locally
pnpm openapi:check

7. Debugging

• pnpm verify:simulate <certId> — runs the public verify flow and prints decision tree.
• pnpm template:render <templateId> — outputs HTML + PDF to ./tmp/preview/.
• pnpm openbadges:show <certId> — prints JSON-LD VC.