---
title: "Setup"
description: "Learn how to install and run the open-source version of the walt.id Issuer2 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/issuer2/setup
generated: 2026-07-20
---
# 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/issuer-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 7002:7002 \
  -itv $(pwd)/waltid-services/waltid-issuer-api2/config:/waltid-issuer-api2/config \
  -t waltid/issuer-api2
```

The `-v` flag mounts `waltid-services/waltid-issuer-api2/config` from the cloned repository into the container. This directory contains the service configuration files (e.g. server port, credential profiles, metadata). 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/issuer2/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:7002`. You can confirm it is running by opening `http://localhost:7002/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-issuer-api2:publishImageToLocalRegistry
# image: waltid/issuer-api2:<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-issuer-api2:publishImage
# image: docker.io/<DOCKER_USERNAME>/issuer-api2:<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 7002:7002 \
  -itv $(pwd)/waltid-services/waltid-issuer-api2/config:/waltid-issuer-api2/config \
  -t waltid/issuer-api2
```

The `-v` flag mounts `waltid-services/waltid-issuer-api2/config` from the cloned repository into the container. This directory contains the service configuration files (e.g. server port, credential profiles, metadata). 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/issuer2/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:7002`. You can confirm it is running by opening `http://localhost:7002/swagger` in your browser.

## Start Issuing Credentials

Now that the Issuer2 API is running, you can start issuing credentials:

1. [Issue a Credential](https://docs.walt.id/community-stack/issuer2/credential-issuance/sd-jwt-vc.md) - Issue your first credential from a ready-made profile, no configuration needed.
2. [Configure Credential Profiles](https://docs.walt.id/community-stack/issuer2/credential-profiles/overview.md) - Define reusable configurations for your own credential types.
3. [Create Credential Offers](https://docs.walt.id/community-stack/issuer2/credential-offers/overview.md) - Generate OID4VCI credential offer URLs.
4. [Full API Reference](https://docs.walt.id/community-stack/issuer2/full-api-reference.md) - Explore all available endpoints via Swagger.