Deployment

Meratyn ships as one React codebase deployed three ways — browser, desktop, and Jupyter — plus a admin console and hosted-layer services for organizations running a shared deployment. This page covers how each artifact is built and served; Build and platform maintenance covers keeping them healthy over time.

Artifacts at a glance

Browser

The web build is fully static: Bun compiles the app, and any static file server works. The root Dockerfile builds the app with Bun and serves it from nginx. It enables the same-origin /sidecar proxy, so the optional Python sidecar can be reached without CORS setup; confine it with MAPPVIEW_CONVERSION_ROOTS (default /data).

Build-time behavior is configured through VITE_ variables (for example VITE_MAPPVIEW_VIEWER_URL, VITE_MAPILLARY_GRAPH_ENDPOINT). The Docker build stage exposes them as ARGs with local-development defaults; override them for your deployment. Credentials are never baked in: see Redistributable artifact boundary.

The Dockerfile also builds the self-hosted JupyterLite site used by the Notebook panel; the build fails rather than silently serving a fallback if that static site is absent.

For pushing to the production VPS, bun run deploy:mapptech builds the exact current commit into a tarball. The local strategy builds the TanStack Start host (docker/Dockerfile.viewer-host), packages its SSR runtime, and the remote host assembles docker/Dockerfile.viewer-local around that artifact. The server strategy builds the same host directly on the deployment server. Both paths keep / as the editor and resolve /<published-slug> through the publication service, with /healthz available for service checks.

The launcher selects the native deployment entrypoint for the host: Windows uses scripts/deploy/mapptech.ps1, while Linux and WSL use scripts/deploy/mapptech.sh. The WSL path requires the OpenShip API to be reachable from WSL; it never falls back to Windows executables for project work. Validate published routes with the Playwright showcase configuration (SHOWCASE_VIEWER_URL and SHOWCASE_ADMIN_URL); an HTTP 200 alone can still be the editor SPA fallback.

Desktop

bun run tauri:build

Tauri v2 produces platform installers (MSI/NSIS on Windows, DMG on macOS, deb/AppImage on Linux) under apps/mappview/src-tauri/target/release/bundle/. The bundle embeds the Python sidecar (services/server) as a resource; at launch the shell starts it with uv run --frozen, which is why services/server/uv.lock is committed and must stay in sync.

Additional Windows channels live under packaging/: an MSIX package (bun run msix:build), a portable build (bun run portable:build), and winget manifests.

Linux specifics — WebKitGTK/NVIDIA pacing and the no-AVX fallback — are handled automatically at startup and documented under Linux WebKitGTK/NVIDIA pacing. bun run tauri:build:native-duckdb builds a variant using the native DuckDB library instead of WASM.

Jupyter

bun run build:embed

This produces apps/mappview/dist-embed, which python/hatch_build.py packages into the meratyn wheel together with the anywidget. The build runs the credential scan on the bundled app before shipping. Users install the wheel with pip install meratyn and get the full interface inside a notebook cell. The package’s version is sourced dynamically from python/src/mappview/__init__.py.

Admin console and services

docker/Dockerfile.admin builds the admin console (apps/admin) and its Bun service (services/admin) into one image. Configuration arrives through environment variables (ADMIN_LOCAL_TOKEN, CLERK_PUBLISHABLE_KEY, VITE_MAPPVIEW_* URLs). The companion services — the GeoNode bridge and the edge tile service — have their own Dockerfiles under services/.

Step-by-step self-hosting instructions are in Self-host the admin console. For a production AWS deployment with the browser app on a static host, see Deploy on AWS.

Hosted layers

Operating the hosted-layers infrastructure (GeoNode, tile service, viewer wiring) is documented separately: see Deploy hosted layers.

Documentation site

The Astro docs app (this site) builds with bun run build:docs. CI’s website workflow builds it on every push to main and publishes the static output; docker/Dockerfile.docs is available for self-hosting. The docs content itself lives in docs/ at the repository root, with the Spanish mirror under docs/es/.