Go Passport Issuer

The Go Passport Issuer repository implements a digital passport issuance system that bridges traditional government-issued travel documents with modern privacy-preserving digital identity frameworks. The system validates electronic passport (e-passport) data using Machine Readable Travel Document (MRTD) standards and issues privacy-by-design digital credentials through the IRMA framework.

Getting started

Prerequisites

For Local Development (without Docker)

Go: Version 1.24.0 or later

Node.js: Version 16 or later (for frontend)

ImageMagick 6: Required for image processing

• macOS:

  brew install imagemagick@6

• Linux (Ubuntu/Debian):

  sudo apt-get update
  sudo apt-get install libmagickwand-dev

Configuration

Make sure there is a local-secrets folder in the root directory with a config.json file containing the necessary configuration details. It should look like this:

{
  "server_config": {
    "host": "0.0.0.0",
    "port": 8080
  },
  "irma_server_url": "https://is.staging.yivi.app",
  "issuer_id": "passport_issuer",
  "jwt_private_key_path": "local-secrets/private.pem",
  "credentials": {
    "passport" : {
      "full_credential": "pbdf-staging.pbdf.passport"
    },
    "driving_licence": {
      "full_credential": "pbdf-staging.pbdf.drivinglicence"
    }
    "id_card": {
      "full_credential": "pbdf-staging.pbdf.idcard"
    }
  },
  "storage_type": "memory",
  "driving_licence_cert_paths": [
    "./certificates/v1/CSCA NL eDL-01.cer",
    "./certificates/v2/CSCA NL eDL-02.cer",
    "./certificates/v3/CSCA NL eDL-03.cer"
  ]
}

The jwt_private_key_path should point to a valid RSA private key in PEM format, which is used to sign JWT tokens for the IRMA server.

Running the application

Local Development (without Docker)

Setup Environment (macOS):

# Option 1: Use the setup script
source ./dev-setup.sh

# Option 2: Manually set environment variables
export PKG_CONFIG_PATH="/opt/homebrew/opt/imagemagick@6/lib/pkgconfig"
export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Setup Environment (Linux):

# Usually no extra environment variables needed on Linux
# Just ensure ImageMagick development libraries are installed

Run the backend:

cd backend
go run . --config ../local-secrets/config.json

Run tests:

# On macOS (ensure environment is set up first)
source ../dev-setup.sh
cd backend
go test ./...

# On Linux
cd backend
go test ./...

Run the frontend:

cd frontend
npm install
npm start

API Documentation

The backend serves interactive API documentation using ReDoc at /api/docs. The OpenAPI specification is generated from Go code annotations using swaggo/swag.

View documentation: Navigate to http://localhost:8080/api/docs when the server is running.

Regenerate documentation (after modifying API handlers or models):

# Install swag CLI (one-time setup)
go install github.com/swaggo/swag/cmd/swag@latest

# Regenerate docs
cd backend
go generate ./...

The swag annotations are located in:

• backend/main.go - API metadata (title, version, description)
• backend/server.go - Handler annotations
• backend/models/ - Request/response model annotations

Using Docker Compose

To run both the backend and frontend using Docker Compose, ensure you have Docker and Docker Compose installed. Then, from the root directory of the project, execute:

docker-compose up --build

Troubleshooting

Issue: invalid flag in pkg-config --cflags: -Xpreprocessor error on macOS

Solution: Make sure you're using ImageMagick 6 (not 7) and have set the CGO_CFLAGS_ALLOW environment variable:

brew install imagemagick@6
export PKG_CONFIG_PATH="/opt/homebrew/opt/imagemagick@6/lib/pkgconfig"
export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Issue: wand/MagickWand.h file not found

Solution: This indicates ImageMagick is not properly installed or the PKG_CONFIG_PATH is not set correctly. Verify installation:

brew list imagemagick@6
pkg-config --cflags --libs MagickWand