Nasim SadatandClaude Opus 5.5
e4806f5799
The rename step in init.sh and the guard in deploy/lib.sh are gone. README's procedure is now "Removing the old project"; it keeps the old names until it has run on the server. Migrations stay here (open point 8), and their README says so. AGENTS.md adds the commit-message rule. Not deployed: live still runs Trino. Bands: 4 (Superset), persistence (docs). Rules: 2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
99 lines
5.6 KiB
Markdown
99 lines
5.6 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/` | `atoma_guest.py`: the role "ATOMA 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` |
|
|
|
|
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 |
|
|
| `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 = "ATOMA 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/atoma_guest.py` gives "ATOMA 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/atoma_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".
|