petrolyst-infra/petrolyst-insights/README.md

petrolyst-insights

The Petrolyst customization of Apache Superset 6.1.0: sign-in, roles, look and feel, patches and dashboards. Consumed by the deployment folders of this repository at image-build time. Not runnable standalone: this folder has no Dockerfile, no Compose file, no CI and no secrets. deploy/deploy.sh refuses to deploy if one appears here.

The split follows media-insights (customization) and media-intelligence-docker (deployment): anything that changes how Superset looks or behaves for Petrolyst lives here; anything about how and where it runs lives in stacks/, traefik/, deploy/ and host/.

Layout

Path	What it is	In the image at
superset_config.py	Keycloak sign-in, role mapping, proxy and cookie settings, Redis caches, theme and chart palettes	/app/pythonpath/
petrolyst_security.py	PetrolystSecurityManager: user info and roles from the Keycloak ID token, /login/ straight to Keycloak, /logout/ through Keycloak	/app/pythonpath/
assets/branding/	logos (full colour and white), favicons, app icons	/app/superset/static/assets/branding/, served at /static/assets/branding/…
patches/	runtime patches, fix_*.py with --verify (see its README); empty at start	/app/patches/petrolyst/, applied during the build
dashboards/	exported dashboards and import scripts (see its README)	not in the image

How the image consumes this folder: stacks/fuel-monitoring/compose.yaml passes it to the build as the named context insights, and the Dockerfile copies from it with COPY --from=insights. The image tag is a hash of exactly the inputs above that end up in the image, so a change here rebuilds and recreates only the superset container.

Secrets read

superset_config.py uses _read_secret(name) (copied from media-insights): it prefers /run/secrets/<name> and falls back to an env var for local runs, and fails at boot on an empty value.

Secret	Purpose
superset_secret_key	Flask SECRET_KEY
superset_db_password	password of user superset on the metadata database
keycloak_petrolyst_client_secret	client secret of Keycloak client petrolyst

On the server they come from /opt/petrolyst/secrets/ (see the deployment README).

Sign-in and roles

• Provider: Keycloak realm thedigitalbridge at iam.thedigitalbridge.io, client petrolyst, authorization code flow with PKCE S256. The realm URL can be overridden with KEYCLOAK_REALM_URL.

• Roles come from the client roles of petrolyst, which a protocol mapper puts into the claim petrolyst_roles, and are re-read at every login:

  Keycloak client role	Superset role
  superset-admin	Admin
  superset-editor	Alpha
  superset-viewer	Gamma
  none	Public (no permissions)

• DASHBOARD_RBAC is on: a viewer sees a dashboard once an admin adds the Gamma role (or a custom one) to it.

Look and feel

Source: petrolyst-ui/design/brand/ (tokens 07_UI_Tokens/petrolyst_tokens.css, logos public/brand/, favicons 03_Favicon_App_Icons/), copied on 2026-10-23 from petrolyst-ui commit 2b2e694. Copy again when the brand changes.

• Light theme: action teal #00695C for primary and links, navy #0B1D33 text, #F8FAFC layout, full-colour stacked logo.
• Dark theme: #35C5B6 primary, #071425 / #12263D surfaces, white logo.
• Font: Inter, Superset's default. Satoshi is licence-restricted and is not used.
• Chart palettes: "Petrolyst" categorical (the default, brand teal first) and "Petrolyst Teal" / "Petrolyst Navy" sequential. The categorical palette was validated with the dataviz skill's validator on both chart surfaces; the numbers are in the comment above it in superset_config.py. Charts with more than three series in scatter or map form should fold the rest into "Other".