PH4H App Backend Template
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
- Accessing the Services
- 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
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.
- Open your web browser and navigate to
http://localhost:9083. - You will be redirected to the Keycloak landing page. Click on the Administration Console link.
- 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.