Digg Wallet Local Development Environment

Docker Compose scripts for starting the Digg Wallet environment services locally.

---

Prerequisites

Before running the local environment, ensure the following prerequisites are in place.

1. Install mkcert

mkcert is required to generate trusted local TLS certificates for the Traefik reverse proxy.

Debian/Ubuntu

sudo apt install libnss3-tools mkcert

macOS

brew install mkcert
brew install nss  # Required for Firefox

2. Trust the mkcert CA

Install the local CA in the system trust store so that browsers and tools trust the generated certificates:

mkcert -install

Note: The local issuer CA certificate can be found with cat "$(mkcert -CAROOT)/rootCA.pem"

3. Generate Traefik TLS Certificate

Generate a certificate and key pair for Traefik to serve local HTTPS traffic:

mkdir -p config/traefik/certs
mkcert \
  --cert-file ./config/traefik/certs/wallet-cert.pem \
  --key-file ./config/traefik/certs/wallet-key.pem \
  localhost 127.0.0.1 ::1 10.0.2.2

4. Generate Internal Service Certificates and Keystores

The ecosystem uses a separate local Root CA to issue certificates for all internal services (PID Issuer, Verifier, Wallet Provider, etc.). These are distinct from the Traefik TLS certificate above and are managed via an automation script.

Automated Generation

To (re)generate all ecosystem certificates, keystores, and REUSE-compliant license files, run:

./config/certificates/generate_keystores.sh

This script:

• Generates an EC (P-256) Root CA (if not present).
• Issues certificates for PID Issuer, Verifier, and Wallet Provider.
• Updates the Verifier Trust Store with the PID Issuer's certificate.
• Ensures all files have the correct permissions for Docker containers.

Note: The Wallet Client Gateway keystore (keystore-wallet-app-bff-local.p12) is not generated by this script. It must be copied from the gateway repository to maintain OIDC compatibility with Keycloak.

---

Setup

Follow these steps in order to configure the environment before starting the services.

1. Copy the Environment File

cp .env.example .env

Review the variables in .env and update them as needed for your local setup. The key variable is BASE_URL, which defines the root URL used by all cluster services and defaults to https://localhost.

Android emulator note: Android emulators cannot reach localhost on the host machine. If you are developing for Android, set BASE_URL=https://10.0.2.2 so the emulator can resolve requests to the running services.

2. Set the Host IP

Some services need to reach the host machine from inside Docker. HOST_IP must be set to the host's IP address as seen from inside a Docker container. Run:

source set-host.sh

Note: It is necessary to run this with source so that the environment variable is exported to the current shell session, not just the script's subshell.

Corporate proxy note: If you are behind a corporate proxy, you may need to add the resolved HOST_IP to Docker's noProxy configuration to prevent proxy errors. For example, if echo $HOST_IP yields 172.17.0.1, edit your Docker config and restart Docker:

cat ~/.docker/config.json

{
  "proxies": {
    "default": {
      "httpProxy": "your-regular-proxy",
      "httpsProxy": "your-regular-proxy",
      "noProxy": "your-regular-no-proxy,172.0.0.0/8"
    }
  }
}

---

Running the Environment

1. Pull the Latest Images

docker compose pull

2. Start the Services

docker compose up

---

Services

Service	URL	Description
Demo verifier	https://localhost/demo-verifier	Our verifier demo service
EU reference verifier backend	https://localhost/refimpl-verifier-backend	Backend used by both verifier implementations
EU reference PID issuer	https://localhost/pid-issuer	EU's reference implementation of a PID issuer
Keycloak	https://localhost/idp	Identity provider for the PID issuer
Wallet Provider	https://localhost/wallet-provider	Issues and manages the lifecycle of Wallet Unit Attestations (WUA)
Wallet Client Gateway	https://localhost/wallet-client-gateway	BFF for the wallet app(s)
Wallet Account	https://localhost/wallet-account	Manages user accounts
Wallet Attribute Attestation	https://localhost/wallet-attribute-attestation	Manages user attribute attestations
Traefik	http://localhost:8080	Reverse proxy handling TLS termination

---

Building Images

If you need to add a new application to the Docker Compose setup, its image must be published before it can be pulled and used locally.