PH4H-app-backend/README.md

PH4H PH4H Backend

Template for backend for the IPS PH4H App. A unified health app for Connectathon users to view, merge, and share IPS data securely cross-border. This project provides a backend system composed of the IPS PH4H API for handling business logic and a Keycloak server for authentication and authorization. The entire stack is containerized using Docker and can be easily managed with Docker Compose.

Table of Contents

• Project Overview
• Components
• Prerequisites
• Getting Started
  • Configuration
  • Running the Application
• Accessing the Services
  • Keycloak Admin Console
  • Golang API
• Stopping the Application
• Swagger Documentation

Project Overview

The architecture of this backend system is designed to separate concerns between the application's business logic and user authentication.

Components

• IPS PH4H API: A lightweight, high-performance API that implements the core features of your application. It is protected and requires a valid JWT from an Authorization server to be accessed.
• Authorization: Identity and Access Management solution. It handles user registration, login, and token issuance.

Prerequisites

• Docker
• Go 1.24 Only if you plan to ran the API without docker

Getting Started

Configuration

• Authentication
• IPS PH4H API (WIP)

⚠️ Complete the not implemented calls

This template backend application includes some functionalities that are intentionally left unimplemented. These are meant to be completed by the participant to assess their knowledge of the FHIR/VHL standards.

To complete these functionalities, search the code for the TODO: To be implemented by the participant message. You will find 3 missing functionaties for:

• Implementing an ITI-67 call
• Implementing an ITI-68 call
• Implementing a QR code generation using VHL

After completing these steps, you can proceed to the next section on running the application.

Running the Application

Open a terminal in the root directory of the project and run the following command:

 docker compose --file=./docker/compose.yaml up

This command will:

• Build the Docker image for the IPS PH4H API.
• Pull the official Docker images for Keycloak and Postgres.
• Create and start the containers for all three services.
• Attach your terminal to the logs of all running containers.

Setup Keycloak

After all services are running, you need to setup keycloak to have the correct configurations for the backend to authenticate and create users. Before contuining please follow the instructions here.

Accessing the Services

Keycloak Admin Console

Once the services are running, you can access the Keycloak Admin Console to configure realms, clients, and users.

1. Open your web browser and navigate to http://localhost:9083.
2. You will be redirected to the Keycloak landing page. Click on the Administration Console link.
3. Log in with the admin credentials provided in your configuration

IPS PH4H API

IPS PH4H API will be accessible at http://localhost:9081. You can use a tool like curl or Postman to interact with your API endpoints. Remember that your API endpoints will be protected by Keycloak, so you will need to obtain a valid JWT from Keycloak to make successful requests. There is a helper script, where you can request a token using:

sh scripts/auth.sh access-token

If the token expires you can refresh it with:

sh scripts/auth.sh refresh-token

And to logout you can do:

sh scripts/auth.sh logout

Stopping the Application

To stop and remove the containers, network, and volumes, press Ctrl+C in the terminal where docker-compose is running, and then run the following command:

docker-compose down

Swagger Documentation

To activate Swagger make sure to set API_SWAGGER=true in your .env file and the docker/compose.yaml.

Then, the API docs can be seen in http://localhost:9081/swagger/index.html.