Docker image & API

Run the OpenCred Docker image for headless issuance and verification — cloud, on-prem, and CI/CD. Your infrastructure, your keys.

The OpenCred Docker image is the headless variant of the Desktop client. It exposes an HTTP API (and a CLI) for issuing and verifying credentials — for cloud deployments, on-prem servers, and CI/CD pipelines. It runs in your infrastructure; no data is sent to OpenCred or NFH Trust Labs.

Quick start

# 1. Pull the public image (no auth required)
docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:latest

# 2. Run with a mounted signing key
docker run -p 3100:3100 \
  -e OPENCRED_PORT=3100 \
  -e OPENCRED_API_KEY=your-secret-token \
  -e OPENCRED_KEY_PATH=/secrets/issuer-key.pem \
  -v /path/to/your/key.pem:/secrets/issuer-key.pem:ro \
  ghcr.io/nfh-trust-labs/opencred/opencred-server:latest

# 3. Check it's running
curl http://localhost:3100/v1/health

A healthy server returns 200 OK:

{
  "status": "ok",
  "ready": true,
  "signingKeyLoaded": true,
  "dediConfigured": false,
  "timestamp": "2026-04-07T10:00:00.000Z"
}

If signingKeyLoaded is false, the server returns 503 and cannot issue — check your key source.

Image tags & architecture

docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:latest   # floats
docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:1.2.0    # pin in production

Each version tag is built by CI from a signed git tag and scanned with Trivy (CRITICAL/HIGH fail the build). From v1.2.0 the image is a multi-arch manifest (linux/amd64 + linux/arm64) — Docker pulls the right variant automatically on Apple Silicon, AWS Graviton, Ampere, Raspberry Pi 4/5, and amd64 VMs.

Pin a version in production. :latest can change underneath you on the next release.

Production run (hardened)

docker run -d \
  --name opencred \
  -p 3100:3100 \
  -e OPENCRED_PORT=3100 \
  -e OPENCRED_API_KEY=sk_prod_change_me \
  -e OPENCRED_KEY_PATH=/secrets/issuer-key.pem \
  -e OPENCRED_LOG_LEVEL=info \
  -v /host/path/issuer-key.pem:/secrets/issuer-key.pem:ro \
  --read-only \
  --tmpfs /tmp:noexec,nosuid,size=64m \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  ghcr.io/nfh-trust-labs/opencred/opencred-server:latest

Docker Compose

The repo ships a hardened docker-compose.yml (read-only FS + tmpfs, all caps dropped except NET_BIND_SERVICE, no-new-privileges, /v1/health check every 30s):

docker compose up -d            # start
docker compose logs -f server   # follow logs
docker compose down             # stop

Build from source

docker build -f apps/server/Dockerfile -t opencred:latest .

Multi-stage build on a pinned node:20-alpine base, runs as non-root node, exposes 3100, starts via node apps/server/dist/index.js.

Providing a signing key

Your key stays in your infrastructure — loaded at startup, never transmitted.

• File-based (default): set OPENCRED_KEY_PATH to a PEM, JWK, PKCS#8, or PFX file. For PFX, also set OPENCRED_KEY_PASSWORD.
• Cloud HSM: set OPENCRED_KMS_PROVIDER to aws, azure, or gcp with the provider variables. See the in-repo Cloud HSM guide (AWS KMS, Azure Key Vault, GCP Cloud KMS).

HTTP API

All endpoints are under /v1. Auth is a required Bearer token (OPENCRED_API_KEY); the middleware is fail-closed.

Endpoint	Purpose
GET /v1/health	Readiness + signing-key status
GET /v1/keys	Active signer info
GET /v1/schemas	Available credential schemas
POST /v1/credentials/issue	Issue a single credential
POST /v1/credentials/batch	Batch issuance
POST /v1/credentials/verify	Verify (JSON-LD / vc-jwt / sd-jwt-vc / PixelPass QR / PDF)
POST /v1/credentials/package	Package as printable PDF / QR
POST /v1/credentials/revocation-hash	Compute a revocation hash
POST /v1/credentials/revoke	Revoke a credential
POST /v1/credentials/revocation-status	Check status
GET /v1/metrics	Metrics

For local development only, OPENCRED_DEV_MODE_NO_AUTH=true disables auth. Never use it in production.

CLI

The image bundles an opencred CLI for one-off, no-HTTP operations (issue, verify, package) — handy in shells and CI. See Verifying credentials for opencred verify.

Security defaults

Non-root user · pinned base digests · no secrets in image layers · read-only FS + dropped caps in Compose · JSON-LD contexts bundled at build time (never fetched at runtime) · structured pino logging to stdout with key material redacted. Full model: Security.

---

Related: Verifying credentials · Concepts · Security model