Postgraphile

Background

The Operating Engine offers the GraphQL Read model. The suggested way to access the GraphQL read model is to use Postgraphile, which is described here.

Configuration

Docker image

Postgraphile 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

Postgraphile runs on port 5555 by default.

Database user

A dedicated database user for Postgraphile should be created and configured for the application to start.

Environment variables

Engine

These are the environment variables for the engine application, needed to enable the postgraphile application setup (enabled by default).

Environment variable	Description	Default value
ENGINE_DB_POSTGRAPHILE_USER	Engine DB - Postgraphile user	`null`
ENGINE_DB_POSTGRAPHILE_PASSWORD	Engine DB - Postgraphile password	`null`

Postgraphile

The following environment variables can be configured for Postgraphile:

Environment variable	Description	Default value	Example value
POSTGRAPHILE_PORT	Postgraphile API port	`5555`
POSTGRAPHILE_DB_URL	Database - URL	`null`	`postgres://postgraphile:postgraphile_pwd@localhost:5432/platform`
POSTGRAPHILE_DB_SCHEMA	Database - schema	`noumena`
POSTGRAPHILE_DB_USER	Database - user	`postgraphile`
POSTGRAPHILE_ENGINE_HEALTH_ENDPOINT	Startup - Engine application healthcheck URL	`http://localhost:12000/actuator/health`
POSTGRAPHILE_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 Postgraphile's integration with the authentication server(s):

Environment variable	Description	Default value	Example value
POSTGRAPHILE_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,`
POSTGRAPHILE_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 Postgraphile.

create role postgraphile login password <pwd>;
alter role postgraphile createrole noinherit;
grant connect on database mydatabase to postgraphile;

Docker configuration

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

Make sure to always deploy the same application versions of both the engine and the postgraphile docker images.

# engine application (listed below is only the configuration specific to the postgraphile 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 postgraphile DB user
    ENGINE_DB_POSTGRAPHILE_USER: postgraphile
    ENGINE_DB_POSTGRAPHILE_PASSWORD: <pwd>

# postgraphile
postgraphile:
  image: ghcr.io/noumenadigital/packages/postgraphile:latest
  depends_on:
    - engine
  ports:
    - "${POSTGRAPHILE_PORT:-5555}:5555"
  environment:
    POSTGRAPHILE_DB_URL: jdbc:postgresql://postgraphile:postgraphile_pwd@postgres_db/platform
    POSTGRAPHILE_DB_SCHEMA: engine-schema
    POSTGRAPHILE_DB_USER: postgraphile
    POSTGRAPHILE_ALLOWED_ISSUERS: "http://keycloak:11000/realms/noumena,"
    POSTGRAPHILE_ENGINE_HEALTH_ENDPOINT: "http://engine:12000/actuator/health"
    POSTGRAPHILE_ENGINE_HEALTH_TIMEOUT_SECONDS: 120

For further configuration options, see environment variables (postgraphile).

A complete docker compose file example can be found here.