Nasim SadatandClaude Opus 5.5
d95e6e184a
Theme tokens for the slate surfaces and borders, the logo with the green Y, chart boxes at 16 px with the card shadow. Full figures with the unit in the subheader; every layer of the tabs transparent, so the site's charts sit as boxes in Firefox and Safari too. The Overview gets a Sites filter and the period's scope returns to the time charts (PD-25). The embedded frame can shrink again. A change to the image's inputs: Superset rebuilds on the next deploy. Bands: Superset. Rules: 2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
99 lines
5.7 KiB
Markdown
99 lines
5.7 KiB
Markdown
# 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, `#1F2A33` / `#2A3945` surfaces (PD-26), white logo with the Y in its green.
|
|
- 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".
|