Self-Host Operations and Performance

Use health and preflight diagnostics before debugging clients.

Readiness checks

curl http://localhost:4000/health
curl http://localhost:4000/health/detailed
curl http://localhost:4000/setup/preflight

Together these reports identify degraded dependencies such as missing worker heartbeat, storage issues, unavailable Martin, Valhalla readiness failures, missing Pelias, or missing static renderer. In production, call root diagnostics with internal authorization or use the authenticated Console preflight view.

What to monitor

• API latency, errors, request IDs, and rate-limit responses.
• Postgres connections, slow queries, storage growth, and backup success.
• Redis availability and queue depth.
• Worker heartbeat, failed jobs, and outbox lag.
• Object storage errors, missing artifacts, and bucket policy drift.
• Martin, Valhalla, Pelias, elevation, and static renderer readiness.
• Disk, memory, and swap on build and serving machines.

Worker sizing

Keep geodata worker concurrency conservative until CPU, memory, and disk behavior are measured with your imports. Use S3-compatible storage for production-like artifact serving and direct uploads.

Before running regional or planet-scale routing builds, check:

• Storage provider is S3-compatible MinIO, S3, or R2.
• Root-agent API routes are reachable from the compute host.
• The root-agent service can poll and report progress.
• Disk space covers source data, intermediate build files, final tarballs, and temporary upload parts.
• RAM and swap are sized for the selected Valhalla build target.
• Docker can pull and run the selected Valhalla image.

Start with no-elevation builds. Elevation and DEM generation should be treated as separate capacity planning work after routing graph builds are reliable.

Backup and restore

Test backup and restore before trusting a deployment. At minimum, protect:

• Postgres data.
• Object storage buckets.
• Runtime data directories for PMTiles, fonts, Valhalla, Pelias, and elevation.
• Root-agent state directories and serving activation state.

Use the repository smoke scripts where appropriate:

pnpm smoke:self-host-backup-restore
pnpm smoke:self-host-restart-persistence
pnpm smoke:self-host-support-bundle

Troubleshooting

If public maps are blank, inspect the style JSON, TileJSON, tile URL, and storage artifact availability in that order.

If service APIs fail, check auth first, then the backing service readiness. For example, routing depends on Valhalla graph data, and geocoding depends on Pelias configuration.

Runtime health is separate from build state. A Valhalla or Martin build can succeed while the runtime remains unavailable until the artifact is deployed to a serving worker and the readiness probe passes.

Related

• Error handling
• Data sources
• External compute