How we built a self-hosted vector tile infrastructure.

The VijiMaps mapping stack separates tile generation, tile serving and map presentation. This case study follows the documented VijiTiles implementation using OpenStreetMap, Planetiler, Martin and MapLibre. It describes the architecture and integration lessons; it does not claim measured performance or availability results.

OpenStreetMap → Planetiler → MBTiles → Martin → MapLibre

Explore the project

Choose the map before building the tiles

The starting point is the map the application needs to draw. A source dataset contains far more information than every basemap needs. Our raw basemap profile includes geography, roads, rail, places, country borders and peaks, while excluding points of interest, buildings, ferries and land use. Separate Shortbread and OpenMapTiles profiles support other styles. This makes the layer definition a product decision: a style cannot render a feature that its tiles do not contain.

Build artifacts outside the request path

Planetiler transforms the OpenStreetMap PBF input into MBTiles on the build host. This is a separate stage from serving requests. Planet-scale builds require substantial disk space for input, intermediate files and output; JVM heap is only part of the memory picture because mapped files also use the operating system’s cache. A regional extract is a useful way to validate a profile before committing to a planet build. Once the artifact is ready, Martin reloads the configured tile sources.

Give each serving component a clear job

Martin serves the vector tiles. An nginx edge routes browser requests, while a separate tiles API exposes a catalog, TileJSON and a ready-to-use MapLibre style. The style endpoint accepts language and 3D options so clients can request a document suited to their view. Keeping generation out of this path allows the application to use an already-built dataset without running a build for each request.

Publish a style deliberately

The repository style is a seed, while the published basemap style lives in a Docker volume. Maputnik provides an editing workspace; an exported style is imported into the published copy. External clients consume the same style endpoint as the demo. This distinction matters when debugging: changing a scratch file does not automatically change the map that users see. A useful handover must explain which copy is active and how a new style is published.

Treat glyphs and browser access as part of the map

A working tile endpoint is insufficient if labels or styles fail to load. The documented stack includes a font preparation step because mismatched font-family names can produce misleading binary parsing errors in MapLibre. CORS is applied at the nginx edge, with duplicate CORS headers disabled in downstream services. Testing a complete style in a browser checks the resources and response headers that a tile-only health check misses.

What we would validate for another deployment

Coverage, update cadence, build capacity and recovery requirements should be agreed before selecting a host. Then validate representative tiles, language labels, style URLs, glyphs and optional terrain or building layers together. The next step is measuring the intended workload on the chosen infrastructure. The architecture alone does not establish throughput, hosting cost or an uptime guarantee.

Plan your next project

Explore our software development services