This is a shareable, pre-configured instance of the Interoperability Test Bed for WHO GDHCN Trust Network purposes, designed for validating HCERTs (Health Certificates) using VHL and ICVP test cases.
New to WHO-ITB? Check out the User Guide for step-by-step instructions on:
- Running Docker and loading the configuration
- Logging in and changing your password
- Navigating to conformance statements and starting test sessions
- Running HCERT with VHL test cases
- Running ICVP test cases
- Repository contents
- Prerequisites
- Installation
- HCERT Test Cases
- Building and Deployment
- Running Test Cases
- Users
- Architecture
- Links
As a quick overview, this repository contains:
- A running, pre-configured Interoperability Test Bed instance (GITB) with all required containers;
- GDHCN helper service for HCERT decoding and SMART Health Link processing;
- SMART helper service for FHIR transformation and validation;
- MatchBox FHIR validation server;
- HAPI FHIR server;
- An initial configuration with communities, organizations, users and admins;
- Test suites for HCERT validation:
- VHL (Verifiable Health Link) test suite
- ICVP (International Certificate of Vaccination and Prophylaxis) test suite
- Generic QR Code Signature Verification test suite
- Git
- Docker with compose
- A browser
- Internet connection (for pulling Docker images)
- Basic knowledge of ITB test case development
-
Clone the repository:
git clone https://github.com/WorldHealthOrganization/WHO-ITB cd WHO-ITB -
Start the composition with Docker on your local machine:
docker-compose up --build
This will start the following services (accessible from your host machine):
- ITB Test Bed UI at http://localhost:10003
- HCERT Validator (GDHCN helper) at http://localhost:8089
- FHIR Server (HAPI) at http://localhost:8080
- MatchBox at http://localhost:8087
- SMART Helper at http://localhost:8000
-
Go to http://localhost:10003 in your browser.
-
Log in with a predefined user (see Users section below).
-
If you ever want to drop the instance and start up from scratch again, then just remove the composition together with the volumes and start from point 2:
docker compose down -v
This repository includes test suites for HCERT (Health Certificate) validation covering three main scenarios:
Test Case: Track 1 - System Utilizes and Validates HCERT: VHL
This test validates:
- QR Code Decoding: Decode QR code image to HC1 string
- HCERT Decoding: Base45 decode, ZLIB decompress, and extract COSE/CWT structure
- Smart Health Link Extraction: Extract SHLink reference from the HCERT payload
- Authorization: Authorize with PIN to access the manifest
- FHIR Resource Retrieval: Fetch and decrypt FHIR resources from the VHL
- Validation: Validate the retrieved IPS bundle against the LACPass RACSEL IPS 0.1.0 profile
Test Case: Track 2 - System Utilizes and Validates HCERT: ICVP
This test validates:
- QR Code Decoding: Decode ICVP QR code image to HC1 string
- HCERT Decoding: Base45 decode, ZLIB decompress, and extract ICVP payload from CWT
- Implementation Guide Installation: Upload required IGs to MatchBox
- FHIR Transformation: Transform ICVP claim to IPS Bundle using StructureMap
- Validation: Validate the transformed IPS Bundle against the IPS profile
Test Case: Generic QR Code signature verification test suite
This test validates:
- QR Code Upload: Upload a barcode image
- QR Code Decoding: Decode QR code image to HC1 string
- HCERT Decoding: Base45 decode, ZLIB decompress, and extract COSE/CWT payload
- Signature Verification: Verify the QR code signature using COSE cryptographic verification
For detailed test execution instructions, see the User Guide.
For regular use, follow the installation steps above. The system will automatically:
- Build the GDHCN helper service (Python-based HCERT decoder) from source
- Build the SMART helper service (Python-based FHIR transformer) from source
- Pull the MatchBox FHIR validation server image
- Pull the HAPI FHIR server image
- Initialize the ITB with pre-configured test suites
- Set up all required services and dependencies
To completely reset and start fresh:
# Stop and remove all containers, networks, and volumes
docker-compose down -v
# Start from scratch
docker-compose up --buildWarning: This will delete all test data and sessions.
-
Ensure all services are running:
docker-compose ps # Should show all services as "Up" -
Verify service health:
# Check HCERT validator (GDHCN helper) curl http://localhost:8089/health # Check FHIR server curl http://localhost:8080/fhir/metadata # Check MatchBox curl http://localhost:8087/fhir/metadata # Check SMART helper curl http://localhost:8000/health
-
Access ITB UI: http://localhost:10003
-
Login with test user:
- Username:
[email protected] - Password:
change_this_password(change on first login)
- Username:
-
Navigate to Test Sessions:
- Go to "Conformance Statements" or "Test Sessions" menu
- You will see available test suites
-
Run VHL Test Case:
- Select "Track 1: System Utilizes and Validates HCERT: VHL"
- Click "Test" or "Create Test Session"
- Upload a QR code image containing an HCERT with VHL reference
- Provide PIN when prompted (e.g.,
1234for test data) - Review the validation results
-
Run ICVP Test Case:
- Select "Track 2: System Utilizes and Validates HCERT: ICVP"
- Click "Test" or "Create Test Session"
- Upload an ICVP QR code image
- Wait for IG installation and transformation (may take 30-60 seconds)
- Review the validation results
For detailed step-by-step instructions, see the User Guide.
Users are set up with temporary passwords, you need to change it immediately after the first login.
| Username | Password | Role | Purpose |
|---|---|---|---|
| your email id | change_this_password | Tester | Execute validation tests |
| [email protected] | change_this_password | Tester | Execute validation tests |
| [email protected] | change_this_password | Admin | Configure test suites and manage users |
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ ITB Test Bed │ │ GDHCN Helper │ │ SMART Helper │
│ (port 10003) │◄─┤ (port 8089) │ │ (port 8000) │
│ │ │ HCERT Decoder │ │ FHIR Transform │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ │ ▼
│ │ ┌─────────────────┐
│ │ │ MatchBox │
│ │ │ (port 8087) │
│ │ │ FHIR Validator │
│ │ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ HAPI FHIR Server (port 8080) │
│ FHIR Resource Storage │
└─────────────────────────────────────────────────────────────┘
- ITB Test Bed: Orchestrates test execution and provides UI
- GDHCN Helper: Python-based service for HCERT decoding and SMART Health Link processing
- SMART Helper: Python-based service for FHIR transformation using StructureMaps
- MatchBox: FHIR validation server with IG support
- HAPI FHIR Server: General-purpose FHIR server for resource storage
- Test Cases: XML-based test definitions following GITB TDL specifications
- QR Code Upload: User uploads QR code image via ITB UI
- HCERT Decoding: GDHCN helper decodes HC1 string to COSE/CWT structure
- SHLink Extraction: Extract Smart Health Link reference from payload
- Authorization: User provides PIN to authorize VHL access
- FHIR Retrieval: GDHCN helper fetches encrypted FHIR resources
- Validation: SMART helper validates retrieved IPS bundle
- Report Generation: ITB generates comprehensive test report
- QR Code Upload: User uploads ICVP QR code image via ITB UI
- HCERT Decoding: GDHCN helper decodes HC1 string and extracts ICVP claim
- IG Installation: SMART helper uploads required IGs to MatchBox
- Transformation: SMART helper transforms ICVP claim to IPS Bundle via StructureMap
- Validation: MatchBox validates the transformed bundle against IPS profile
- Report Generation: ITB generates comprehensive test report
Key configuration parameters in docker-compose.override.yml:
services:
hcert-validator:
ports:
- "8089:8080" # External port 8089 maps to internal container port 8080
environment:
- PYTHONUNBUFFERED=1
fhir-server:
ports:
- "8080:8080"
environment:
- hapi.fhir.cr.enabled=true
matchbox:
ports:
- "8087:8080"
smart-helper:
ports:
- "8000:8000"
environment:
- FHIR_HOST=http://fhir-server:8080/fhir # Internal Docker network address
- MATCHBOX_HOST=http://matchbox:8080/matchboxv3/fhir # Internal Docker network addressNote: The environment variables use internal Docker network addresses (e.g., http://fhir-server:8080). These are different from the external host access URLs (e.g., http://localhost:8080).
The ITB is configured with HCERT-specific domain settings:
- Domain: WHO HCERT Validation
- Test Suites: VHL and ICVP validation
- Test Data: Pre-loaded sample data in
test-data/directory
-
Services Not Starting:
# Check service status docker-compose ps # Check logs docker-compose logs hcert-validator docker-compose logs smart-helper docker-compose logs fhir-server docker-compose logs matchbox
-
HCERT Validator Connection Issues:
# Test validator connectivity curl http://localhost:8089/health # Check network connectivity docker network ls docker network inspect who-itb_default
-
FHIR Server Issues:
# Test FHIR server curl http://localhost:8080/fhir/metadata # Test MatchBox curl http://localhost:8087/fhir/metadata # Test SMART helper curl http://localhost:8000/health
-
Test Execution Failures:
- Check test case XML syntax in
testsuites/directory - Verify all services are running and healthy
- Review service logs for error messages
- Ensure test data files exist in
test-data/directory
- Check test case XML syntax in
- Increase Docker memory allocation for large test suites (recommended: 4GB+)
- Wait for all services to fully initialize before running tests
- MatchBox IG installation may take 30-60 seconds on first run
- Default passwords must be changed immediately
- Consider running on isolated networks for production testing
- Implement proper certificate management for mTLS connections
- Regular security updates for all container images
This testing composition uses the Interoperability Test Bed as the main tool of orchestrating and reporting test-cases. See further resources on it below.
- User Guide: Step-by-step guide for running tests and using the system