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/
roles/	petrolyst_guest.py: the role "Petrolyst Guest" for the Petrolyst app's embedded dashboards, with exactly its permissions; run by hand (see "Embedding")	/app/petrolyst-roles/
assets/branding/	logos (full colour and white): the wordmark alone for the navbar, and the stacked logo; favicons, app icons; ATOMA's logo, which the Petrolyst app shows in its map's corner (the server reads this file itself: PETROLYST_OPERATOR_LOGO_FILE)	/app/superset/static/assets/branding/, served at /static/assets/branding/…
patches/	runtime patches, fix_*.py with --verify (see its README); none at present	/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, realm petrolyst; on the server in shared/keycloak_petrolyst_realm_client_secret

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

Sign-in and roles

• Provider: Keycloak realm petrolyst 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
  atoma-reader	none (Public): ATOMA's users use the Petrolyst app, not Superset (PD-13)
  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.

• FILTERBAR_CLOSED_BY_DEFAULT is on: a dashboard's filter column opens collapsed, a narrow strip with an expand button; ?expand_filters=true opens it from a link.

Embedding (local trial only)

The Petrolyst app (PD-12, petrolyst-platform app/ and server/) shows dashboards inside its Insights lens with Superset guest passes. This is switched on only in the local scratch stack (.local/fmdb-scratch); superset_config.py here leaves it off, and loads without the guest secret.

• The scratch stack's superset_config_local.py turns on EMBEDDED_SUPERSET, names the guest role GUEST_ROLE_NAME = "Petrolyst Guest", reads the signing secret with _read_secret("superset_guest_token_secret") and expects the audience petrolyst-app. The Petrolyst server signs the guest passes itself with the same secret.

• roles/petrolyst_guest.py gives "Petrolyst Guest" exactly what a dashboard needs to be read. Which dashboard a guest sees comes from the pass, not the role. It is not in init.sh; run it once, and again whenever its permissions change:

  docker exec <superset> /app/.venv/bin/python /app/petrolyst-roles/petrolyst_guest.py
  

• The app's dashboards and their embedding ids: dashboards/README.md.

Production embedding is an open point of PD-12 (.context/design-decisions.md).

Look and feel

Source: petrolyst-web/design/brand/ (tokens 07_UI_Tokens/petrolyst_tokens.css, logos public/brand/, favicons 03_Favicon_App_Icons/), copied on 2026-10-23 from petrolyst-web (then 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".