Skip to main content

​
Overview

VCVerifier is provided as a container image and can be run using Docker. The official image is available on Quay.io and supports multi-architecture builds (amd64/arm64).

​
Quick start

Run VCVerifier with default configuration: 
docker run -p 8080:8080 quay.io/fiware/vcverifier
The service will be available at http://localhost:8080.

​
Configuration

​
Environment variables

VCVerifier loads configuration from a YAML file. You can specify a custom configuration file location using the CONFIG_FILE environment variable: 
docker run -p 8080:8080 \
  -e CONFIG_FILE=/config/custom-config.yaml \
  -v $(pwd)/config:/config \
  quay.io/fiware/vcverifier
If CONFIG_FILE is not set, the default configuration is loaded from ./server.yaml in the container’s working directory.

​
Volume mounts

Mount configuration files and keys into the container: 
docker run -p 8080:8080 \
  -v $(pwd)/server.yaml:/app/server.yaml \
  quay.io/fiware/vcverifier

​
Container details

​
Build process

The VCVerifier container is built using a multi-stage Dockerfile: 
FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS build

ARG TARGETOS
ARG TARGETARCH

WORKDIR /go/src/app
COPY ./ ./

RUN apk add --no-cache build-base
RUN go mod download
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -ldflags="-s -w" -o VCVerifier .

FROM alpine:3.23

LABEL org.opencontainers.image.source="https://github.com/FIWARE/VCVerifier"

WORKDIR /app

COPY --from=build /go/src/app/views ./views
COPY --from=build /go/src/app/VCVerifier ./VCVerifier
COPY --from=build /go/src/app/server.yaml ./server.yaml

ENV GIN_MODE=release

CMD ["./VCVerifier"]

​
Default environment

  • Base image: Alpine Linux 3.23
  • Working directory: /app
  • Default port: 8080
  • Runtime mode: Release mode (via GIN_MODE=release)

​
Configuration example

1

Create configuration file

Create a server.yaml file with your configuration:
server.yaml
server:
  port: 8080
  templateDir: "views/"
  staticDir: "views/static/"

logging:
  level: "INFO"
  jsonLogging: true
  logRequests: true

verifier:
  did: did:key:myverifier
  tirAddress: https://tir.de
  sessionExpiry: 30
  generateKey: true
  supportedModes: ["urlEncoded", "byReference", "byValue"]
  
configRepo:
  configEndpoint: http://config-service:8080
2

Run container with configuration

docker run -d \
  --name vcverifier \
  -p 8080:8080 \
  -v $(pwd)/server.yaml:/app/server.yaml \
  quay.io/fiware/vcverifier
3

Verify the service is running

Check the container logs:
docker logs vcverifier
Test the service:
curl http://localhost:8080/health

​
Advanced configuration

​
Custom templates

Mount custom HTML templates for the login page: 
docker run -p 8080:8080 \
  -v $(pwd)/custom-views:/app/views \
  -v $(pwd)/static-content:/app/views/static \
  quay.io/fiware/vcverifier
The template directory must contain a verifier_present_qr.html file that includes the QR code via <img src="data:{{.qrcode}}"/>.

​
Using private keys

When not using generateKey: true, mount your private key file:
server.yaml
verifier:
  generateKey: false
  keyPath: /keys/private-key.pem
  keyAlgorithm: RS256

docker run -p 8080:8080 \
  -v $(pwd)/server.yaml:/app/server.yaml \
  -v $(pwd)/keys:/keys \
  quay.io/fiware/vcverifier

​
Networking with other services

Connect VCVerifier to other services using Docker networks: 
# Create a network
docker network create vc-network

# Run config service
docker run -d \
  --name config-service \
  --network vc-network \
  your-config-service:latest

# Run VCVerifier
docker run -d \
  --name vcverifier \
  --network vc-network \
  -p 8080:8080 \
  -v $(pwd)/server.yaml:/app/server.yaml \
  quay.io/fiware/vcverifier

​
Health checks

Add health checks to your Docker deployment: 
docker run -d \
  --name vcverifier \
  -p 8080:8080 \
  --health-cmd="wget -q --spider http://localhost:8080/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  quay.io/fiware/vcverifier

​
Docker Compose

For a complete setup with multiple services:
docker-compose.yml
version: '3.8'

services:
  vcverifier:
    image: quay.io/fiware/vcverifier
    ports:
      - "8080:8080"
    volumes:
      - ./config/server.yaml:/app/server.yaml
      - ./keys:/app/keys
    environment:
      - GIN_MODE=release
    networks:
      - vc-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  config-service:
    image: quay.io/fiware/credentials-config-service
    ports:
      - "8081:8080"
    networks:
      - vc-network
    restart: unless-stopped

networks:
  vc-network:
    driver: bridge
Ensure your server.yaml references services by their Docker service names when using Docker Compose (e.g., http://config-service:8080).

​
Troubleshooting

​
Container won’t start

Check the logs for configuration errors: 
docker logs vcverifier

​
Port already in use

Change the host port mapping: 
docker run -p 9090:8080 quay.io/fiware/vcverifier

​
Configuration not loading

Verify the volume mount is correct: 
docker exec vcverifier ls -la /app/server.yaml

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us