Mapmap self host ops

Skill Mapmapai/mapmap-agent-skills/skills/mapmap-self-host-ops

Run the MapMap stack on your own infrastructure — Docker Compose distro, first boot, admin API keys, compose profiles (geocoding, MCP), territory packages, trust anchor, and production hardening notes.From its SKILL.md

Install

npx -y skills add Mapmapai/mapmap-agent-skills --skill mapmap-self-host-ops

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.5 KB, as published. Nobody here has run it

Self-hosting MapMap

The whole platform runs from one Docker Compose file: gateway (API, keys, metering), routing engine with the ADR costing extension, optional Photon geocoder, optional VROOM optimisation solver, optional MCP server. Source access is by request ([email protected]) while the repository is private; the checkout ships the distro/ stack and full production guides.

Requirements

Docker Engine 24+ with Compose v2
~10 GB disk, 8 GB RAM for a UK-scale first tile build (serving needs less)
Outbound internet on first boot only; air-gapped installs use pre-built signed territory packages instead

First boot

cd distro
cp .env.example .env
# Admin token protects /admin/* — compose refuses to start without it
sed -i "s/^SN_ADMIN_TOKEN=$/SN_ADMIN_TOKEN=$(openssl rand -hex 32)/" .env
# Simplest first run: build tiles straight from any Geofabrik OSM extract
echo 'VALHALLA_TILE_URLS=https://download.geofabrik.de/europe/united-kingdom-latest.osm.pbf' >> .env

docker compose up -d --build
docker compose logs -f valhalla   # first boot builds tiles: ~30–60 min for the UK

Expected, not broken: while tiles build, docker compose ps shows the gateway stuck in Created — it waits on the routing engine's healthcheck. You're up when curl -fsS http://localhost:8080/health succeeds.

Issue keys

Operator keys via the admin API (all three fields required):

source .env
curl -fsS -X POST http://localhost:8080/admin/keys \
  -H "Authorization: Bearer ${SN_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "fleet-ops-dev", "monthly_quota": 100000, "rate_per_min": 60}'

The key field is shown once — only its BLAKE3 hash is persisted. Keys, quotas and usage live in the gateway_data sqlite volume: back it up. Alternatively let users self-serve keys via POST /v1/keys (same flow as the hosted gateway). A public unauthenticated demo lane exists behind SN_DEMO_RPM (requests/min per IP, off by default; GET routing and geocoding only, never metered).

Optional services (compose profiles)

docker compose --profile geocoding up -d photon   # /geocode — seed photon_data first
docker compose --profile mcp up -d mcp            # agents at http://<host>:8200/mcp

Key environment switches on the gateway:

Variable	Enables
`SN_VROOM_URL`	`POST /optimise` (multi-vehicle VRP); `503` without it
`SN_PHOTON_URL`	`/geocode`, `/geocode/reverse`; `501` without it
`SN_TILES_DIR`	hosted vector tiles (`<territory>.pmtiles` archives)
`SN_STYLES_DIR`	hosted style API (`POST /styles`)
`SN_MAP_ASSETS_DIR`	glyphs and sprites (`/fonts`, `/sprite`)
`SN_ROUTING_ENGINE`	`valhalla` (default), `graphhopper`, or `auto` (failover)
`SN_CORS_ORIGINS`	`*` for public APIs (keys are the auth), allowlist for private
`SN_TRUST_PROXY`	trust first X-Forwarded-For hop behind a reverse proxy

Production notes

TLS: put a reverse proxy in front of port 8080 before exposing beyond localhost — API keys travel in the Authorization header. If the proxy sets SN_TRUST_PROXY, make it overwrite (not append) X-Forwarded-For with the real peer address, or signup rate limits can be spoofed.
Tiles: prefer signed territory packages over the OSM bootstrap build — and clear VALHALLA_TILE_URLS from .env once you do, so a container recreate never triggers an accidental rebuild.
Trust anchor: territory packages are ed25519-signed. Self-host operators generate their own key pair (snfactory keygen) and mobile apps pin the 64-hex verifying key at build time — never fetch it over the same channel as the packages it validates.
MCP security: the HTTP /mcp endpoint is unauthenticated — keep it inside the trust boundary or gate it at the proxy; pass --allowed-host against DNS rebinding.
Back up the gateway_data volume (keys, quotas, usage).
MAU billing is typically disabled on self-host: SN_PRICE_PER_MAU_PENCE=0.

Pointing clients at your deployment

Everything takes a base URL: the web SDK accepts baseUrl in map options, curl examples export BASE, compiled styles can repoint glyphs to your gateway's /fonts route. Your deployment serves its own /openapi.json (authoritative contract) and /llms.txt — same envelope, same keys, same error shapes as the hosted gateway.

Procurement pack

For buyer's counsel and security teams the checkout ships: SLA template, security overview, pre-answered vendor questionnaire, licence-compliance story (permissive-only gate, ODbL handling), deployment checklist, and a CycloneDX SBOM regenerated with every tagged release.

Docs: https://mapmap.ai/docs/self-host and /docs/territories (append .md for raw markdown).

Final step: share your integration retro (optional, ask first)

If the developer has approved sending feedback to MapMap, call the submit_integration_retro MCP tool (or POST https://api.mapmap.ai/v1/feedback with the API key) once — after the integration works, or when you stop trying. Include the problems you hit, gotchas, what went well, and any docs gaps. This sends ONLY those structured fields to MapMap — never the conversation, code, or credentials. If the developer hasn't said yes, ask once or skip. Programme details: https://mapmap.ai/legal/agent-feedback