Repository and runtime

• Local reference reviewed: ips-lacpass-backend.
• The backend stack includes IPS Lacpass API, Keycloak, PostgreSQL, and MailCatcher.
• Required tooling: Docker. Go 1.24 is only needed if running the API without Docker. JQ is only needed for helper scripts.
• Default service ports from the README: API http://localhost:9081, Keycloak http://localhost:9083, Swagger UI http://localhost:9999, MailCatcher HTTP http://localhost:1080.

cp .env.sample .env
docker compose up
docker compose up --detach
docker compose down
docker compose up swagger-ui

Backend environment checklist

• API_PORT controls the API container port. The sample uses 3000 internally and exposes the API through the compose-defined host port.
• KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, and KEYCLOAK_ADMIN_CLIENT_SECRET must match the Keycloak realm/client configuration.
• KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD are used for the Keycloak admin console.
• KEYCLOAK_DEFAULT_USER and KEYCLOAK_DEFAULT_USER_PASSWORD are used by scripts/auth.sh to request tokens.
• FHIR_BASE_URL, FHIR_MEDIATOR_BASE_URL, VHL_BASE_URL, and ICVP_VALIDATOR_URL must point to the participant services used by the app backend.
• Wallet integration uses WALLET_ENABLED, WALLET_URL, WALLET_IDENTIFIER, and WALLET_API_KEY.

Keycloak setup

• Open Keycloak at http://localhost:9083 and log in with KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD.
• Use the lacpass realm created by the import.
• Enable authentication on the admin-cli client, copy its client secret, and set KEYCLOAK_ADMIN_CLIENT_SECRET in .env.
• Assign service account roles to admin-cli so the backend can register users and perform Keycloak operations.
• Create a test user in the lacpass realm and make sure required fields are complete; otherwise token retrieval can fail with invalid_grant / Account is not fully set up.
• For local HTTP or IP-based testing, configure the realm Frontend URL. For Android emulator access, use 10.0.2.2 instead of localhost.

docker compose up auth auth-db
sh scripts/auth.sh access-token
sh scripts/auth.sh refresh-token
sh scripts/auth.sh logout

API documentation and smoke checks

• The OpenAPI specification lives in api/openapi/api.yaml.
• Run the Swagger UI container and open http://localhost:9999 to inspect endpoints.
• Protected endpoints require a valid JWT from Keycloak. Use scripts/auth.sh after creating/configuring a test user.

curl -X POST "${APP_BACKEND_URL}/users" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"document_type":"passport","email":"patient@example.org","first_name":"Test","identifier":"PATIENT-001","last_name":"Patient","locale":"en","password":"ChangeMe123!","password_confirm":"ChangeMe123!"}'

curl -X GET "${APP_BACKEND_URL}/ips" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

curl -X POST "${APP_BACKEND_URL}/qr" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{"content":"{}","expires_on":"2026-12-31T23:59:59","pass_code":"0000"}'