Proxy

Introduction

Proxy or message capture is a component that used to capture the messages exchanged between two systems under test. This tool is also bind to the EVSClient in order to validate the messages stored in the Proxy in a very simple way.

Proxy or Message Capture (Version 2.0.0 and higher)

Introduction

The Proxy 2.0.0 has externalized the low-level operations of the channels in a dedicated service based on Netty 4, allowing for a clearer separation between transport management and protocol processing, and improving the maintainability and modularity of the overall system.

Installation

Prerequisites

  1. Java 17 or higher
  2. Maven 3.8.x
  3. PostgresSQL 15 or higher
  4. Docker
  5. Optional: Mandrel 17 (for native compilation)

Build

  1. Clone the project: 
     git clone [PROXY_V17_URL]
  2. Build the project: 
     mvn clean install -DskipTests
  3. Prepare the database:
    • Create a PostgreSQL database named channel-manager and a user gazelle.
    • Run the SQL script located in proxy-quarkus/src/main/resources/db/migration/V1__init.sql to initialize the database schema.

      Run

We can run the Channel Socket Service using the following command:

java -jar proxy-quarkus/target/quarkus-app/quarkus-run.jar

Configuration

The proxy is configured using JVM properties. The following table describes the properties that can be used to configure the proxy component.

Variable name Description Default value
datahouse.url The URL used to communicate with datahouse, to record messages and connections http://localhost:8080/datahouse/rest/v1
quarkus.http.port The port of the service 8081
quarkus.log.level The log level INFO
proxy.fallback.pipeline.enabled Enable/disable fallback record true
proxy.fallback.record.service.url Recording service URL for the fallback pipeline (alternative to datahouse, ex: proxy v7) http://localhost:8380/proxy/rest
service.ip.address Ip of the host machine of proxy. Used in HTTP rewrite 127.0.0.1
handler.logger.enabled Enable/disable logger handler to log incoming/outgoing messages false
quarkus.swagger-ui.always-include Enable/disable swagger graphical interface true
quarkus.otel.exporter.otlp.traces.endpoint Service URL to export opentelemtry spans, if not set, telemetry will be disabled http://localhost:4317

Gazelle Admin Interface - Channel Manager UI

The Gazelle Admin Interface is a core component of Proxy that oversees the lifecycle of communication channels. It manages the creation, configuration, and supervision of various channel types—such as TCP, HTTP, DICOM, and Syslog to intercept and record messages exchanged between systems under test.

The Gazelle Admin Interface communicates with the proxy to control these channels, delegating operations such as starting, stopping, and updating channel configurations through its API.

Installation

Gazelle Admin Interface is a Channel Manager UI component that provides the user interface for managing channels, including creation, deletion, configuration, listing, and updating of channels.

Prerequisites

  1. Node.js 18 or higher
  2. pnpm with command pnpm install -g pnpm

Build

  1. Clone the project: 
     git clone [gazelle-admin-interface-url]
  2. Build the project: In your project root: 
     cd gazelle-admin-interface
 pnpm install

    Run

    To run the Channel Manager UI, use the following command:

     pnpm run dev

    The UI should now be accessible at:

    http://localhost:3000/gazelle/channels

    Configuration

There is a set of properties that you can configure on env that should be on the root of the project.

Property name Description Example of value
BASE_PATH_CHANNEL Base path used to mount the admin interface routes /gazelle/admin
HOME_URL URL to redirect users after login or when clicking “Home” https://qualif3.ihe.kereval.cloud/home/
PROXY_URL The base URL of the proxy admin frontend (used for redirection/navigation) http://localhost:3001
USERS_URL URL to the external user management interface (GUM UI) https://qualif3.ihe.kereval.cloud/gum-ui/users
REGISTRATION_URL URL to the user registration page https://qualif3.ihe.kereval.cloud/gum-ui/registration
CHANNEL_URL UI base URL of the current channel management interface http://localhost:3000/
CHANNEL_API_URL REST API base URL for managing channels (provided by the backend proxy engine) http://localhost:8086/proxy/rest/v1/
USERS_API_URL API endpoint for user information from the GUM backend http://localhost:8081/gum/rest/users
KEYCLOAK_CLIENT_ID Keycloak OIDC client ID used for authentication OIDC_GAZELLE_CLIENT
KEYCLOAK_ISSUER Keycloak issuer URL (realm endpoint for token  

Message Capture

The messages captured by the Proxy can be viewed and managed through the Message Capture. The interface allows users to filter, search, and validated captured messages, providing a comprehensive view with all messages per connection exchanged on a specific channel

Installation

The Message Capture is a component of the Gazelle User Interface that provides a user interface for viewing and managing captured messages.

Prerequisites

  1. Node.js 18 or higher
  2. pnpm with command pnpm install -g pnpm
  3. Gazelle User Interface installed and running
  4. Datahouse service running

Build

  1. Clone the project: 
     git clone [gazelle-user-interface-url]
  2. Build the project: In your project root: 
     cd gazelle-user-interface
 pnpm install

    Run

    To run the Gazelle User Interface, use the following command:

    pnpm run dev

    The UI should now be accessible at:

    Configuration

    The Message Capture component can be configured using environment variables. The following table describes the properties that can be used to configure the Message Capture component.

Property name Description Example of value
HOME_URL URL to redirect users after login or when clicking “Home” https://qualif3.ihe.kereval.cloud/home/
PROXY_URL Base URL of the proxy frontend http://localhost:3000
USERS_URL URL to the external user management UI https://qualif3.ihe.kereval.cloud/gum-ui/users
REGISTRATION_URL URL to the user registration page https://qualif3.ihe.kereval.cloud/gum-ui/registration
CHANNEL_URL Base URL of the current channel management UI http://localhost:3000/
FQDN Fully qualified domain name used to compose base URLs localhost:3000
SCHEME Protocol scheme (http or https) http
BASE_URL Full base URL composed from scheme and FQDN http://localhost:3000
KEYCLOAK_CLIENT_ID Keycloak client ID for OIDC authentication OIDC_GAZELLE_CLIENT
KEYCLOAK_ISSUER Keycloak realm issuer URL http://localhost:28080/realms/gazelle
NEXTAUTH_URL NextAuth.js callback URL http://localhost:3000/gazelle/api/auth
NEXTAUTH_SECRET Secret for NextAuth.js encryption Gd/amKSF7eFZ3YdPNvMuFYKil3j/Ycq8BpnRvpaRpFY=
GZL_DTH_API_URL Base URL for DataHouse backend http://localhost:8082/datahouse/rest/v1
GZL_DTH_EVSGATEWAY_URL Base URL for EVS Gateway service (DataHouse validation engine) https://qualif2.ihe.kereval.cloud/evsgateway/rest/v1
GZL_DTH_VALIDATION_ENABLED Enables validation in DataHouse true
GDH_PRESENTATION_SCHEMA_PATH Path to the DataHouse presentation schema JSON /opt/datahouse-ui/presentationSchemas.json
GZL_GUM_API_URL GUM API base URL http://localhost:8081/gum/rest
GZL_TEXEC_API_URL Test Execution API base URL http://localhost:8080/test-execution/rest
GZL_TM_URL Test Management frontend URL http://localhost:8080/gazelle
GZL_GUM_UI_URL GUM frontend user management UI URL http://localhost:3000/gazelle/user-management
GZL_TEST_CASE_FOLDER Path to the test case directory /opt/gazelle-user-interface/test-execution/test-case/
GZL_HOME_CONFIGURATION_FOLDER Path to the home configuration folder /opt/gazelle-user-interface/home

Installation via Docker

You can run the Proxy and Gazelle Admin Interface using Docker.

Prerequisites

  1. Docker Compose installed on your machine.
  2. Docker image for the Channel Socket Service and Channel Manager UI available.

Build Docker Image

  1. Clone the project from: 
     git clone [PRJECT_URL]
  2. Pull the Docker image and run the container: 
     docker-compose up -d