Setup
Installation & Running the Project
Make sure you have Docker installed on your machine.
Option 1: Using Docker Pull
1. Clone the Identity Repo
Clone the repository to your local machine. The repo contains the default configuration files that will be mounted into the container in the next step.
git clone https://github.com/walt-id/waltid-identity.git && cd waltid-identity
2. Pull the Docker Image
Pull the pre-built Docker image from Docker Hub:
docker pull waltid/verifier-api2
3. Run the Docker Image
Run the container, mounting the config directory from the cloned repository. This gives the service its default configuration — see the note below for details.
docker run -p 7003:7003 \
-itv $(pwd)/waltid-services/waltid-verifier-api2/config:/waltid-verifier-api2/config \
-t waltid/verifier-api2
The -v flag mounts waltid-services/waltid-verifier-api2/config from the cloned repository into the container. This directory contains the service configuration files (e.g. server port, trust store settings). You can edit these files before starting the container to customise the service behaviour.
See the configuration reference for a full description of all available config files and their fields.
Once the container starts, the API is available at http://localhost:7003. You can confirm it is running by opening http://localhost:7003/swagger in your browser.
Option 2: Building the Image Yourself
This option requires Java (JDK 17+), Gradle, and Docker to be installed on your machine.
1. Clone the Identity Repo
Clone the repository to your local machine:
git clone https://github.com/walt-id/waltid-identity.git && cd waltid-identity
2. Build the Docker Image If you prefer to build the Docker image yourself, use the Gradle Ktor/Jib tasks:
# Development (local Docker daemon, single-arch)
./gradlew :waltid-services:waltid-verifier-api2:publishImageToLocalRegistry
# image: waltid/verifier-api:<version>
# Production (multi-arch push to your registry)
export DOCKER_USERNAME=<your-dockerhub-namespace>
export DOCKER_PASSWORD=<your-dockerhub-token>
./gradlew :waltid-services:waltid-verifier-api2:publishImage
# image: docker.io/<DOCKER_USERNAME>/verifier-api:<version>
Note: multi-arch images require a registry push. Local tar output is single-arch only.
3. Run the Docker Image
After building the image, run it using (adjust the image name if you pushed to your registry):
docker run -p 7003:7003 \
-itv $(pwd)/waltid-services/waltid-verifier-api2/config:/waltid-verifier-api2/config \
-t waltid/verifier-api2
The -v flag mounts waltid-services/waltid-verifier-api2/config from the cloned repository into the container. This directory contains the service configuration files (e.g. server port, trust store settings). You can edit these files before starting the container to customise the service behaviour.
See the configuration reference for a full description of all available config files and their fields.
Once the container starts, the API is available at http://localhost:7003. You can confirm it is running by opening http://localhost:7003/swagger in your browser.
Start Verifying Credentials
Now that the Verifier2 API is running, choose the credential type that matches your use case: