KYC Service — Deployment¶

Prerequisites¶

Node.js 20+
npm
Redis (BullMQ queue backend)
PostgreSQL (Serverpod database — writes to kyc_verification)
Gemini API key (or local Ollama instance)
CompreFace instance (face matching)
Garage / S3-compatible storage (KYC document images)

Install Dependencies¶

cd projects/kyc-service
npm install

Environment Variables¶

Copy .env.example to .env and fill in all values:

cp .env.example .env

Variable	Required	Default	Description
`PORT`	No	`3003`	HTTP listen port
`POSTGRES_URL`	Yes	—	PostgreSQL connection string
`REDIS_URL`	Yes	—	Redis connection URL
`S3_ENDPOINT`	Yes	—	Garage/S3 endpoint URL
`S3_REGION`	No	`1-wallet`	S3 region identifier
`S3_ACCESS_KEY`	Yes	—	S3 access key ID
`S3_SECRET_KEY`	Yes	—	S3 secret access key
`S3_BUCKET`	No	`kyc-data`	S3 bucket name
`KYC_SERVICE_SECRET`	Yes	—	Shared secret for inbound auth (`X-Service-Token`)
`GEMINI_API_KEY`	Conditional	—	Required when `KYC_PROVIDER=gemini` (default)
`KYC_PROVIDER`	No	`gemini`	AI provider: `gemini` or `ollama`
`OLLAMA_URL`	No	`http://localhost:11434`	Ollama base URL (when `KYC_PROVIDER=ollama`)
`OLLAMA_MODEL`	No	`gemma4`	Ollama model name
`COMPREFACE_URL`	No	`http://localhost:8000`	CompreFace base URL
`COMPREFACE_API_KEY`	Yes	—	CompreFace verification service API key
`FACE_MATCH_THRESHOLD`	No	`0.75`	Minimum face similarity to accept (0.0–1.0)
`PII_ENCRYPTION_KEY`	Yes	—	AES key for encrypting OCR results (base64, 32 bytes). Must match Serverpod `piiEncryptionKey`
`KYC_STUCK_TIMEOUT_MIN`	No	`15`	Minutes before watchdog marks stuck `in_review` records as failed

Database¶

The KYC service writes to kyc_verification in the public schema, which is owned and created by Serverpod's migration system. No separate SQL init script is needed — the table is created by Serverpod when the Auth Center starts.

Run¶

Development (with auto-reload via nodemon):

npm run dev

Production:

npm start
# or
node src/index.js

Health Check¶

GET /health
→ 200 { "status": "ok" }

Use this endpoint for load balancer or container health probes.

CompreFace Setup¶

CompreFace must be running before the service starts. At startup the service checks GET {COMPREFACE_URL}/healthcheck and logs a warning if unreachable (does not abort startup, but face matching will fail until CompreFace is available).

CompreFace requires a named Docker volume to persist data:

docker run -d \
  -v compreface_data:/app/data \
  -p 8000:8000 \
  exadel/compreface:latest

See CompreFace documentation to create a verification service and obtain the COMPREFACE_API_KEY.

Docker¶

A Dockerfile is present in projects/kyc-service/. Build and run:

docker build -t kyc-service .
docker run -d \
  --env-file .env \
  -p 3003:3003 \
  kyc-service