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	postgraphile
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_TRUSTED_ISSUERS	Comma-delimited list of trusted JWT issuers, using prefix matching; use of ** in the URLs for arbitrary path matches has been deprecated	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_TRUSTED_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.