# 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.