> For the complete documentation index, see [llms.txt](https://docs.empe.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.empe.io/develop/wallet-server/environment-and-setup.md). # Environment & Setup *These steps are only required when self-hosting the wallet-server. You can skip this section if you deploy from Empeiria's One-Click Deployment Portal.* ## Prerequisites * Node.js 20+ * Yarn 1.22.x (the repo pins `yarn@1.22.22` via `packageManager`) * PostgreSQL 14+ (tested with 16.x) ## Configuration (.env) Create a `.env` file in the wallet-server root. Configuration is read from environment variables; the service validates the required ones at startup and refuses to boot if any are missing. ### Required * **`DATABASE_URL`** — PostgreSQL connection string for the datastore, e.g. `postgres://user:pass@localhost:5432/ssi`. * **`ISSUER_BASE_URL`** — public base URL under which this service serves OpenID4VCI issuer endpoints and credential offers. Any base URL works; by convention it ends with the protocol's path segment, e.g. `https://issuer.example.com/oid4vci` (and `https://verifier.example.com/oid4vp` for the verifier URL below). * **`VERIFIER_BASE_URL`** — public base URL under which this service serves OpenID4VP verifier endpoints. As with the issuer URL, a protocol path suffix is typically appended (e.g. `https://verifier.example.com/oid4vp`). ### Authentication Every non-public endpoint requires a valid OIDC JWT **Bearer** token (`Authorization: Bearer `). Tokens are validated against a JWKS endpoint. * **`OIDC_JWKS_URL`** — JWKS endpoint used to verify access tokens (e.g. a Keycloak realm's `.../protocol/openid-connect/certs`). Required unless `AUTH_DISABLED=true`. * **`AUTH_DISABLED`** — set to `true` for local development only. Every request is then treated as an authenticated admin, so no token is needed. Never enable this in production. ### did:web hosting The hostname for a `did:web` is supplied per request, in the required `domain` field of `POST /agent/did/web` (e.g. `issuer.example.com`, optionally with a port such as `example.com:8080`). There is no environment-variable fallback. Hosted `did:web` documents are keyed by a generated UUID and served by this service over HTTPS at a fixed route; there is no configurable path prefix. See "did:web & Hosting" for path rules and examples. ### Other * **`PORT`** — HTTP port (default `3000`). * **`ALLOW_INSECURE_HTTP`** — set to `true` to allow plain HTTP URLs during local development. OpenID4VC requires HTTPS in production, so leave this unset (or `false`) outside of local testing. * **`NODE_ENV`** — when set to `production`, unhandled error messages returned to clients are replaced with a generic `Internal server error`; the real cause is only written to the logs. ### Example ``` PORT=3000 # Datastore DATABASE_URL=postgres://postgres:postgres@localhost:5432/ssi # Public base URLs (a protocol path suffix is typically appended) ISSUER_BASE_URL=https://issuer.example.com/oid4vci VERIFIER_BASE_URL=https://verifier.example.com/oid4vp # Authentication (JWKS endpoint for OIDC Bearer tokens) OIDC_JWKS_URL=https://auth.example.com/realms/empe/protocol/openid-connect/certs # Local-only shortcut: skip token validation, treat every caller as admin # AUTH_DISABLED=true # Local development over plain HTTP (never enable in production) # ALLOW_INSECURE_HTTP=true ``` ## Install & Run ``` yarn install yarn start:dev # or yarn build && yarn start:prod ``` Swagger UI: `http://localhost:/api-docs` OpenAPI JSON: `http://localhost:/api-docs-json` A global rate limit of 60 requests per 60 seconds applies (serving of DID documents is exempt). ## Database * The datastore is **PostgreSQL**, configured through a single `DATABASE_URL` connection string. * Database migrations run automatically at startup; no separate flag or command is required. * Stored data includes hosted DID documents, tenant signing keys, credential schemas, issuance and verification session state, and credentials held by cloud wallets. ## did:web Hosting Notes * This service creates **`did:web`** and **`did:key`** (Ed25519) identifiers and serves the `did:web` documents itself. * A hosted `did:web` document is served at `GET /:uuid/did.json` (and at `GET /:uuid/.well-known/did.json`), where `:uuid` is the identifier generated when the DID is created. * The `did:web` identifier is built from the `domain` supplied in the `POST /agent/did/web` request body plus a generated UUID, producing a DID of the form `did:web:issuer.example.com:`. * See "did:web & Hosting" for path rules and examples. ## Requirements The wallet server runs as part of the EVDI **SSI Core** stack and shares its runtime requirements: **Node.js 20** and **PostgreSQL 16**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.empe.io/develop/wallet-server/environment-and-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.