---
title: "Setup"
description: "Learn how to install and run the open-source version of the walt.id verifier2 API."
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/verifier2/setup
generated: 2026-07-08
---
# 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.

```bash
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:

```bash
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.

```bash
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.

**Note:**

See the [configuration reference](https://docs.walt.id/community-stack/verifier2/configurations/feature-manager.md) 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

**Note:**

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:

```bash
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:

```bash
# Development (local Docker daemon, single-arch)
./gradlew :waltid-services:waltid-verifier-api2:publishImageToLocalRegistry
# image: waltid/verifier-api:<version>
```

```bash
# 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):

```bash
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.

**Note:**

See the [configuration reference](https://docs.walt.id/community-stack/verifier2/configurations) 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:

- [W3C Verifiable Credentials via OID4VP](https://docs.walt.id/community-stack/verifier2/credential-verification/vc-oid4vp.md)
- [SD-JWT VC via OID4VP](https://docs.walt.id/community-stack/verifier2/credential-verification/sd-jwt-vc-oid4vp.md)
- [Mobile Driver's Licenses (mDL) via OID4VP](https://docs.walt.id/community-stack/verifier2/credential-verification/mdl-oid4vp.md)
- [Verifiable Credentials via Digital Credentials API](https://docs.walt.id/community-stack/verifier2/credential-verification/dc-api.md)
- [Full API reference](https://docs.walt.id/community-stack/verifier2/full-api-reference.md)