petrolyst-infra/petrolyst-insights/dashboards/README.md

dashboards/

Superset dashboards as code and the operator scripts that import them. Not baked into the image, so changes here do not rebuild or restart Superset.

• atoma/: the ATOMA dashboard, with a Map tab (the fleet map) and an Insights tab (one site's details), shown to readers as a lens switch in the navbar. SPEC.md is the design; build_bundle.py generates the import bundle and import_bundle.py imports it (overwriting the objects the bundle defines). dashboard.css is the dashboard's own CSS, which the bundle carries.

  The Fleet tab is an iframe of the fleet-map view from the petrolyst-platform repository. It needs that view and its read service served on Superset's own origin under /views, and the image's superset_config.py with the iframe setting (SPEC.md §6). Without them the tab stays empty, and the Site details tab works as before.

  Build and import:

  docker cp atoma/import_bundle.py fuel-monitoring-superset-1:/tmp/
  docker exec fuel-monitoring-superset-1 /app/.venv/bin/python /tmp/import_bundle.py --show-database
  python3 atoma/build_bundle.py --database-uuid <printed uuid> --out atoma-dashboards.zip
  docker cp atoma-dashboards.zip fuel-monitoring-superset-1:/tmp/
  docker exec fuel-monitoring-superset-1 /app/.venv/bin/python /tmp/import_bundle.py /tmp/atoma-dashboards.zip --user <username>
  

  Exit status 2 means a dataset's columns differ from its view: regenerate atoma/columns.tsv (command in its header), rebuild and import again.

  The import attaches the role "ATOMA Reader" to the dashboard (a bundle cannot carry roles), so the role must exist first: superset-init creates it (petrolyst-insights/roles/). The Fleet tab shows ATOMA's logo from petrolyst-insights/assets/branding/atoma_logo.svg, in the image.

  An import never deletes. On an instance that still has the two dashboards from before 28 Oct 2026 ("ATOMA - Sites" and "ATOMA - Site Detail") and their charts M1, M3, M4 and M5, delete those by hand after importing.

  The bundle also carries the Petrolyst app's dashboards (PD-12, SPEC.md §10): atoma-overview (fleet totals) and atoma-site (one site, its four sections as tabs; it replaced atoma-site-summary, -fuel, -runtime and -baseline on 29 Oct: delete those by hand where they exist). They get no role; the app shows them with guest passes (see "Embedding" in the parent README; local stack only). Add --embedded-out FILE --embed-domain <app origin> to the import to make them embeddable from the app's origin; FILE then receives {slug: embedding id} for the app service. The ids stay the same across imports. Local stack:

  docker exec fmdb-scratch-superset /app/.venv/bin/python /tmp/import_bundle.py /tmp/atoma-dashboards.zip \
      --user admin --embedded-out /tmp/embedded-dashboards.json --embed-domain http://127.0.0.1:8098
  docker cp fmdb-scratch-superset:/tmp/embedded-dashboards.json <Petrolist>/.local/fmdb-scratch/
  

Export from a running instance (inside the container, as the server's deploy user):

docker exec fuel-monitoring-superset-1 superset export-dashboards -f /tmp/dashboards.zip
docker cp fuel-monitoring-superset-1:/tmp/dashboards.zip .

Import is the reverse with superset import-dashboards -p <zip> -u <username>. The username must be an existing Superset user, which here means someone who has signed in through Keycloak at least once.