Environment & Setup

Those steps are only required when self-hosting DID wallet-server. You can skip this section if you deploy from Empeiria's One-Click Deployment Portal.

Prerequisites

• Node.js 20+

• npm 10+ (or Yarn)

• PostgreSQL 14+ (tested with 17.x)

Configuration (.env)

Create a .env file in the wallet‑server root. Key variables:

• PORT: HTTP port (default 3000)

• DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE

• DB_MIGRATIONS_RUN: true to auto‑run TypeORM migrations on boot

• JWT_PROVIDER_PUBLIC_KEY: Base64‑encoded DER (SPKI) public key used to verify access tokens

• DID_WEB_DOMAIN: required FQDN/host for did:web

• DID_WEB_JSON_PATH: optional base path (may include :id placeholder)

• DID_WEB_PORT: optional port if serving did:web on non‑default ports

• ENABLE_DEBUG_SIGN_ENDPOINT: true to expose /auth/debug/* endpoints (never enable in prod)

Example:

PORT=3000

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=wallet
DB_MIGRATIONS_RUN=true

# Public key as Base64 DER (SPKI). Do not paste PEM.
JWT_PROVIDER_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...

# did:web configuration
DID_WEB_DOMAIN=example.com
# Optional: base path; supports ":id" placeholder
DID_WEB_JSON_PATH=/did/user/:id
# Optional: include if non‑default
DID_WEB_PORT=443

# Debug (local only)
ENABLE_DEBUG_SIGN_ENDPOINT=false

Tip: Use the debug keypair endpoint (see Security) to generate compatible Base64 keys for local testing.

Install & Run

npm install
npm run start:dev
# or
npm run build && npm run start:prod

Swagger: http://localhost:<PORT>/api-docs OpenAPI JSON: http://localhost:<PORT>/swagger.json

Database

• Migrations run automatically when DB_MIGRATIONS_RUN=true (and are explicitly run at boot).

• Tables include DID documents, keys, secrets, and verifiable credentials.

did:web Hosting Notes

• The server serves did.json at GET /did/user/:id/did.json for each user.

• The actual did:web DID is built from DID_WEB_DOMAIN and DID_WEB_JSON_PATH.

• See “did:web & Hosting” for path rules and examples.