Self Deployment

Introduction

We support two container-based methods in order to self-host the services needed to back Veridian wallet:

A more traditional, single-host Docker Compose installation.
A more customizable one for reliability and scalability — using a Helm chart to deploy to Kubernetes.

In any case, we try to make it as easy and simple to go from zero to orchestrating all the services and serving them behind HTTPS. This keeps Web2 compatibility, although of course, the end-goal is to get rid of this need while enabling ToIP (Trust over IP) using KERI.

Common pre-requisites

You will need a registered DNS domain. We reference it as PUBLIC_DOMAIN but it’s OK as long as it’s reachable from your wallet app and the server(s) you will be deploying to.
- At least these DNS records under this domain that resolve to the cloud instance or load-balancer that will be serving the services:
  - cred-issuance
  - cred-issuance-ui
  - keria
  - keria-boot
  - keria-ext
  - witness-0 to witness-5 (6 records in total)
A cloud instance or k8s cluster with enough resources to run the services. We recommend at a minimum 4vCPU, 8GB of RAM and 20GB of storage to start with.

Docker Compose guide

Pre-requisites

Docker and Docker Compose installed.
A cloud instance with a public IP address.
- DNS records described above resolving to this IP address.
- TCP ports 80 and 443 open.
A valid email address for Let’s Encrypt HTTPS certificate management (although they will be expedited automatically).

Installation

Clone the repository and enter the directory:


git clone https://github.com/cardano-foundation/veridian-wallet.git
cd veridian-wallet

Copy the .env.production-traefik file to .env.production:


cp .env.production-traefik .env.production

Edit the .env.production file and set the PUBLIC_DOMAIN and ACME_ADMIN_EMAIL variables.
Initialize witnesses’ configuration:


docker compose \
    --profile witness-init \
    --env-file .env.production \
    -f docker-compose.production-traefik.yaml \
    up

Boot up witnesses:


docker compose \
    --profile witness \
    --env-file .env.production \
    -f docker-compose.production-traefik.yaml \
    up -d

Initialize KERIA’s configuration by following these steps:

a. Generate a fresh KERIA_PASSCODE and update the value in the .env.production file:


KERIA_PASSCODE=$(docker run -it --rm cardanofoundation/cf-keria-passcode-gen)
sed -i "s/^KERIA_PASSCODE=.*/KERIA_PASSCODE=$KERIA_PASSCODE/" .env.production

b. Gather witnesses’ OOBIs and check that they all (0-5) look correct:


export KERIA_IURLS=$(INITIAL_PORT=5642; for wit in $(seq 0 5); do OOBI=$(docker compose -f docker-compose.production-traefik.yaml logs witness-$wit 2>/dev/null | grep Witness.wit | awk '{print $NF}'); echo http://witness-$wit:$(( INITIAL_PORT + wit ))/oobi/${OOBI}/controller?role=witness; done | xargs echo)
echo $KERIA_IURLS

c. Setup KERIA’s configuration:


docker compose \
    --profile keria-init \
    --env-file .env.production \
    -f docker-compose.production-traefik.yaml \
    up

Boot up the rest of the services:


docker compose \
    --profile production \
    --env-file .env.production \
    -f docker-compose.production-traefik.yaml \
    up -d

It may take a few minutes for the certificates to be issued and put in place, and for the services to be fully operational, but at this point you should be able to access the services at URLs like https://cred-issuance-ui.$PUBLIC_DOMAIN.

Helm guide

Pre-requisites

A Kubernetes cluster with an ingress controller capable of handling TLS termination for the chosen PUBLIC_DOMAIN.
kubectl installed.
- kubectl configured to access the k8s cluster.
helm installed.

Installation

This guide will describe the installation using our provided installation script. It will make the installation process easier than manually applying the Helm chart!

In case you want to do it manually, you can find the Helm chart source and documentation here .

Download AND review the script:


curl -so /tmp/helm-install.sh https://raw.githubusercontent.com/cardano-foundation/cf-helm-charts/refs/heads/main/charts/cf-idw/helm-install.sh

Execute the script with the required environment variables:


export NAMESPACE=cf-idw-services
export WITNESS_COUNT=6  # Number of witnesses to deploy
export PUBLIC_DOMAINS=3x4mpl3.com,example.com  # Comma-separated list of public domains where the deployment will be served from
bash /tmp/helm-install.sh

Get the full list of URLs if you already have an ingress controller managing SSL certificates:


for host in $(kubectl get ingress -n ${NAMESPACE} -o jsonpath='{.items[*].spec.rules[*].host}'); do
  echo https://$host
done | sort