Read Model

Background

The Operating Engine offers the GraphQL Read Model, which is described here. The Read Model is a separate application that provides the GraphQL API.

Configuration

Docker image

The Read Model is provided as a docker image which includes a default configuration. It uses the same versioning as the rest of the platform (including, most importantly, the engine).

API

The Read Model runs on port 5555 by default.

Database user

A dedicated database user for the Read Model should be created and configured for the application to start. The read model database user does not manage its own schema, but it must access the data. Make sure to provide it with GRANT CONNECT ON DATABASE privileges.

Refer to the example setup for more details.

Environment variables

Engine

These are the environment variables for the engine application, needed to enable the Read Model application setup (disabled by default).

Environment variable	Description	Default value
ENGINE_DB_READ_MODEL_USER	Engine DB - Read Model user	n/a (optional value)

Read Model

The following environment variables can be configured for the Read Model:

Environment variable	Description	Default value	Example value
READ_MODEL_PORT	Read Model API port	5555
READ_MODEL_DB_URL	Database - URL	n/a (mandatory value)	postgres://read_model:read_model_pwd@localhost:5432/platform
READ_MODEL_DB_SCHEMA	Database - schema	noumena
READ_MODEL_DB_USER	Database - user	read_model
READ_MODEL_ENGINE_HEALTH_ENDPOINT	Startup - Engine application healthcheck URL	http://localhost:12000/actuator/health
READ_MODEL_ENGINE_HEALTH_TIMEOUT_SECONDS	Startup - Time in seconds to wait for the Engine application startup	5

Authentication

The following environment variables can be configured to set up the Read Model's integration with the authentication server(s):

Environment variable	Description	Default value	Example value
READ_MODEL_ALLOWED_ISSUERS	Comma-delimited list of trusted JWT issuers. JWTs are only accepted if the value in the iss field matches one of these values exactly.	http://localhost:11000/realms/noumena
READ_MODEL_ISSUER_OVERRIDE	Instead of extracting the issuer from the iss field, always use this URL as the issuer; for development purposes only		https://override.example.com

Example setup

Database user setup

The following SQL script creates a dedicated database user for the Read Model.

-- the use of 'noinherit' is regarded good practice, Read Model user privileges are obtained by explicit 'set role'
create role read_model login password <pwd> noinherit;
grant connect on database mydatabase to read_model;

Docker configuration

The engine will provide all database-level privileges needed for the Read Model database user. For this to happen, make sure to configure the variables that are related to the engine, i.e. ENGINE_DB_READ_MODEL_USER.

Make sure to always deploy the same application versions of both the Engine and the Read Model Docker images.

# engine application (listed below is only the configuration specific to the Read Model application)
engine:
  image: ghcr.io/noumenadigital/packages/engine:latest
  depends_on:
    - postgres_db
  # ...
  environment:
    # ...
    ENGINE_DB_URL: "jdbc:postgresql://postgres_db/platform"
    ENGINE_DB_SCHEMA: engine-schema
    ENGINE_DB_USER: engine
    ENGINE_DB_PASSWORD: engine_pwd
    # setup Read Model DB user
    ENGINE_DB_READ_MODEL_USER: read_model

# Read Model
read-model:
  image: ghcr.io/noumenadigital/packages/read-model:latest
  depends_on:
    - engine
  ports:
    - "${READ_MODEL_PORT:-5555}:5555"
  environment:
    READ_MODEL_DB_URL: "jdbc:postgresql://read_model:read_model_pwd@postgres_db/platform"
    READ_MODEL_DB_SCHEMA: engine-schema
    READ_MODEL_DB_USER: read_model
    READ_MODEL_ALLOWED_ISSUERS: "http://keycloak:11000/realms/noumena"
    READ_MODEL_ENGINE_HEALTH_ENDPOINT: "http://engine:12000/actuator/health"
    READ_MODEL_ENGINE_HEALTH_TIMEOUT_SECONDS: 120

For further configuration options, see environment variables (Read Model).

A complete docker compose file example can be found here.