Skip to content
OpenCharly

versatiles-frontend

Recipe card from the charly-versa plugin (Images — the deployable catalog).

versatiles-frontend — VersaTiles tile-content explorer SPA

Section titled “versatiles-frontend — VersaTiles tile-content explorer SPA”

Layer properties

Section titled “Layer properties”
Property Value
Dependencies supervisord, versatiles-style (re-exported under /style/)
Distros arch + fedora
Build deps curl, jq
Ports 8002 (host-mapped to 28002)
Service versatiles-frontend (supervisord, restart: always, priority 38)
Static dist /opt/versatiles-frontend/

Why pre-built tarball (not npm build)

Section titled “Why pre-built tarball (not npm build)”

versatiles-org/versatiles-frontend ships pre-built static SPAs on every release (four variants: frontend, frontend-dev, frontend-min, frontend-tiny). We pick frontend (full feature set) since the versa image targets interactive exploration, not minimal embedding. Build deps (nodejs, npm, vite) are NOT needed inside the versa image — saves ~250 MB image size.

This contrasts with /charly-versa:maputnik-layer which DOES build from source (npm ci + npm run build -- --base=/) because maputnik ships no pre-built tarball.

Service spec

Section titled “Service spec”
service:
  - name: versatiles-frontend
    exec: /usr/bin/python3 -m http.server 8002 --directory /opt/versatiles-frontend
    restart: always
    working_directory: /opt/versatiles-frontend
    priority: 38
    enable: true
    scope: system

Mirrors maputnik (priority 34) and pmtiles-viewer (priority 35). All three are stdlib python3 http.server processes — no shared infrastructure, easy to debug independently.

Bundle layout

Section titled “Bundle layout”

After the install task completes, /opt/versatiles-frontend/ contains:

Path Source
index.html unpacked from frontend.tar.gz
assets/, tile-data/, … unpacked from frontend.tar.gz
style/versatiles-style.js, style/... copied from /opt/versatiles-style/ so the notebook’s iframe can import the bundle via the same http.server

The cross-layer dependency on versatiles-style is declared via require: [supervisord, versatiles-style] — image-build ordering ensures versatiles-style runs first and populates /opt/versatiles-style/ before this layer’s cp -r copies it under /opt/versatiles-frontend/style/.

Check probes

Section titled “Check probes”

Build-scope:

  • versatiles-frontend-index-html — /opt/versatiles-frontend/index.html exists
  • versatiles-frontend-style-bundle — find /opt/versatiles-frontend/style -name 'versatiles-style*.js' -size +1c matches (verifies the cross-layer cp ran)

Deploy-scope:

  • versatiles-frontend-running — supervisord service RUNNING
  • versatiles-frontend-port-reachable — TCP 8002 reachable
  • versatiles-frontend-http-up — GET / returns 200
  • versatiles-frontend-style-fetchable — curl http://localhost:8002/style/ returns success (the directory listing or index file)

Use case in the versa image

Section titled “Use case in the versa image”

Operator opens http://127.0.0.1:28002/ in a browser to:

  1. Explore tile contents from any local versatiles serve or PMTiles archive. The frontend includes interactive map widgets, metadata inspection, and tile-layer toggles.
  2. Test custom styles before pasting into the notebook’s shortbread MapLibre cell.

The frontend ALSO serves the versatiles-style bundle at /style/, which is the load path the notebook’s iframe uses. This is a secondary role of the same http.server — operators don’t need to visit /style/ directly.

Cross-references

Section titled “Cross-references”