ArchiTools/geoportal/TILE-SERVER-EVALUATION.md

Tile Server Evaluation — ArchiTools Geoportal (March 2026)

Context

ArchiTools Geoportal serves vector tiles (MVT) from PostgreSQL 16 + PostGIS 3 via Martin. Data: ~330K GIS features (parcels, buildings, admin boundaries) in EPSG:3844 (Stereo70), growing to 1M+. Frontend: MapLibre GL JS 5.21, Next.js 16, Docker self-hosted via Portainer CE.

---

Problem Statement

1. Martin v0.15.0 was running in auto-discovery mode — the existing martin.yaml config was never mounted
2. Building labels (cadastral_ref) missing from MVT tiles despite the view exposing them
3. Performance concerns at scale (330K -> 1M+ features)

---

Solutions Evaluated (7 options + emerging tech)

1. Martin (Fix + Upgrade) — WINNER

Aspect	Detail
Root cause	martin.yaml not mounted in docker-compose — Martin ran in auto-discovery mode
Fix	Bake config into custom image via Dockerfile + upgrade v0.15 -> v1.4.0
Performance	Fastest tile server benchmarked (2-3x faster than #2 Tegola)
EPSG:3844	Native support via default_srid: 3844
New in v1.4	ZSTD compression, MLT format, materialized views, better logging

Status: IMPLEMENTED AND VERIFIED IN PRODUCTION (2026-03-27)

2. pg_tileserv (CrunchyData)

Aspect	Detail
Architecture	Go binary, zero-config, delegates ST_AsMVT to PostGIS
Property control	Auto from schema + URL ?properties= parameter
Performance	2-3x slower than Martin (Rechsteiner benchmark)
EPSG:3844	Supported (auto-reprojects via ST_Transform)
Killer feature	Function-based sources (full SQL tile functions)
Dealbreaker	View extent estimation bug (#156) affects all our views, development stagnant (last release Feb 2025)

Verdict: NO — slower, buggy with views, stagnant development.

3. Tegola (Go-based)

Aspect	Detail
Architecture	Go, TOML config, explicit per-layer SQL
Performance	2nd in benchmarks, but 2-3x slower than Martin
Built-in cache	File, S3/MinIO, Redis — with seed/purge CLI
EPSG:3844	NOT SUPPORTED (only 3857/4326) — requires ST_Transform in every query
Killer feature	Built-in tile seeding and cache purging

Verdict: NO — EPSG:3844 not supported, dealbreaker for our data.

4. t-rex (Rust-based)

Aspect	Detail
Status	Abandoned/unmaintained — no releases since 2023

Verdict: NO — dead project.

5. GeoJSON Direct from Next.js API

Aspect	Detail
330K features	~270 MB uncompressed, 800 MB-1.4 GB browser memory
Browser impact	10-30s main thread freeze, mobile crash
Pan/zoom	Full re-fetch on every viewport change, flickering
Viable range	Only at zoom 16+ with <500 features in viewport

Verdict: NO — does not scale beyond ~20K features.

6. PMTiles (Pre-generated)

Aspect	Detail
Architecture	Single-file tile archive, HTTP Range Requests, no server needed
Performance	~5ms per tile (vs 200-2000ms for Martin on low-zoom)
Property control	tippecanoe gives explicit include/exclude per property
Update strategy	Full rebuild required (~3-7 min for 330K features)
EPSG:3844	Requires reprojection to 4326 via ogr2ogr before tippecanoe
MinIO serving	Yes — direct HTTP Range Requests with CORS

Verdict: YES as hybrid complement — excellent for static UAT overview layers (z0-z12), Martin for live detail.

7. Emerging Solutions

Solution	Status	Relevance
mvt-rs (Rust)	v0.16.2, active	Admin UI, auth per layer, cache — good for multi-tenant
MLT format	Stable Jan 2026	6x compression, 4x faster decode — Martin v1.3+ supports it
BBOX	Maturing	Similar to Tegola performance, unified raster+vector
DuckDB tiles	Early	Not PostGIS replacement, interesting for GeoParquet
FlatGeobuf	Stable	Good for <100K features, not a tile replacement

---

Benchmark Reference (Rechsteiner, April 2025)

Rank	Server	Language	Relative Speed
1	Martin	Rust	1x (fastest)
2	Tegola	Go	2-3x slower
3	BBOX	Rust	~same as Tegola
4	pg_tileserv	Go	~4x slower
5	TiPg	Python	Slower
6	ldproxy	Java	4-70x slower

Source: github.com/FabianRechsteiner/vector-tiles-benchmark

---

Implementation Roadmap

Phase 1: Martin Fix — DONE (2026-03-27)

Changes applied:

• martin.Dockerfile: custom image that COPY-s martin.yaml into /config/
• docker-compose.yml: Martin v0.15 -> v1.4.0, build from Dockerfile, --config flag
• martin.yaml: comment updated to reflect v1.4
• map-viewer.tsx: building labels layer activated (cladiriLabel at minzoom 16)

Deployment Lessons Learned

1. Docker image tag format changed at v1.0: old tags use v prefix (v0.15.0), new tags do not (1.4.0). The tag ghcr.io/maplibre/martin:v1.4.0 does NOT exist — correct is ghcr.io/maplibre/martin:1.4.0.

2. Portainer CE volume mount pitfall: volume ./martin.yaml:/config/martin.yaml:ro fails because Portainer deploys only the docker-compose.yml content, not the full git repo. Docker silently creates an empty directory instead of failing. Solution: bake config into a custom image with a 2-line Dockerfile:

   FROM ghcr.io/maplibre/martin:1.4.0
   COPY martin.yaml /config/martin.yaml
   

3. Martin config format is stable: YAML format unchanged from v0.15 to v1.4 — postgres.tables, connection_string, auto_publish, properties map all work identically. No migration needed.

4. PostGIS view geometry type: Martin logs UNKNOWN GEOMETRY TYPE for all views — this is normal for nested views (SELECT * FROM parent_view). Views don't register specific geometry types in geometry_columns. Does not affect tile generation or property inclusion.

Phase 2A: nginx Tile Cache

Impact: 10-100x faster on repeat requests, zero PostGIS load for cached tiles. Effort: ~2 hours.

Implementation Prompt

Add an nginx reverse proxy cache in front of Martin for tile serving in ArchiTools.

Context:
- Martin serves tiles at http://martin:3000 (container name: martin, internal port 3000)
- Martin is built from martin.Dockerfile (COPY martin.yaml into image)
- Traefik proxies external traffic to ArchiTools at tools.beletage.ro
- Current tile URL pattern: https://tools.beletage.ro/tiles/{source}/{z}/{x}/{y}
- NEXT_PUBLIC_MARTIN_URL=https://tools.beletage.ro/tiles
- Portainer CE deploys from Gitea repo — files must be in git, not just on host

Requirements:
1. Create an nginx container `tile-cache` in docker-compose.yml
2. nginx config: proxy_cache for all paths with:
   - Cache zone: 2GB max, keys in shared memory
   - Cache valid: 200 responses for 1 hour
   - Stale serving on error/timeout
   - Cache-Control headers passed through
   - CORS headers for tiles (Access-Control-Allow-Origin: *)
   - Gzip/brotli passthrough (Martin already compresses)
3. Route Martin traffic through tile-cache:
   - tile-cache listens on port 3010 (host) -> 80 (container)
   - tile-cache proxies to http://martin:3000
   - Martin removes its host port mapping (only accessible via tile-cache)
4. Volume for persistent cache across container restarts
5. IMPORTANT: nginx config must be baked into a custom image (same pattern as martin.Dockerfile)
   because Portainer CE cannot mount files from the repo. Create nginx/tile-cache.conf and
   a tile-cache.Dockerfile.

Do NOT change the frontend NEXT_PUBLIC_MARTIN_URL — keep the same external URL.
Build with `npx next build` to verify zero errors.

Phase 2B: PMTiles for UAT Overview Layers

Impact: Sub-10ms overview tiles, zero PostGIS load for z0-z12. Effort: ~4-6 hours.

Implementation Prompt

Implement PMTiles pre-generation for UAT overview layers in ArchiTools Geoportal.

Context:
- PostGIS at 10.10.10.166:5432, database architools_db, user architools_user
- Views: gis_uats_z0, gis_uats_z5, gis_uats_z8, gis_uats_z12, gis_administrativ
- All geometries EPSG:3844 (Stereo70), need reprojection to 4326 for tippecanoe
- MinIO at 10.10.10.166:9002 (API) / 9003 (console), bucket for tiles
- Frontend: MapLibre GL JS 5.21 in src/modules/geoportal/components/map-viewer.tsx
- Portainer CE deploys from Gitea — any config files must be baked into Docker images

Requirements:

1. Create `scripts/rebuild-overview-tiles.sh`:
   - Export each view with ogr2ogr: -f FlatGeobuf -s_srs EPSG:3844 -t_srs EPSG:4326
   - Generate combined PMTiles with tippecanoe:
     - --layer per view, --minimum-zoom=0, --maximum-zoom=14
     - --detect-shared-borders (critical for adjacent UAT polygons)
     - --hilbert for compression
   - Atomic upload to MinIO: upload as overview_new.pmtiles, then rename to overview.pmtiles
   - Cleanup temp files

2. Create Dockerfile for tippecanoe build container (or use ghcr.io/felt/tippecanoe)

3. Add `tippecanoe` service to docker-compose.yml (one-shot, for manual/cron runs)

4. Configure MinIO:
   - Create bucket `tiles` with public read
   - CORS: Allow GET/HEAD from tools.beletage.ro, expose Range/Content-Range headers

5. Update map-viewer.tsx:
   - npm install pmtiles
   - Register pmtiles:// protocol on MapLibre
   - Add PMTiles source for overview layers (z0-z14)
   - Keep existing Martin sources for detail layers (z14+)
   - Set zoom breakpoints: PMTiles below z14, Martin above z14

6. Add N8N webhook trigger or cron for nightly rebuild after weekend deep sync

The UAT overview layers change rarely (only when new UATs are synced).
Parcel/building layers stay on Martin for live data freshness.

Build with `npx next build` to verify zero errors.
Read CLAUDE.md for project conventions before starting.

Phase 2C: MLT Format Testing

Impact: 6x smaller tiles, 4x faster client decode. Effort: ~1 hour to test.

Implementation Prompt

Test MLT (MapLibre Tiles) format on one layer in ArchiTools Geoportal.

Context:
- Martin v1.4.0 running with config baked in via martin.Dockerfile
- MapLibre GL JS 5.21 in src/modules/geoportal/components/map-viewer.tsx
- Test layer: gis_terenuri (largest layer, ~250K features)

Requirements:

1. Research how Martin v1.4 serves MLT format:
   - Check if it's automatic via Accept header or needs config
   - Check Martin docs for MLT serving configuration

2. Update map-viewer.tsx to request MLT for one source (gis_terenuri):
   - Add `encoding: "mlt"` to the vector source definition if MapLibre supports it
   - Or configure via source URL parameter if Martin expects it

3. Test and measure:
   - Compare tile sizes: MVT vs MLT for same tile coordinates
   - Compare decode time in browser DevTools Network tab
   - Check that all properties (cadastral_ref, area_value, etc.) survive MLT encoding
   - Check label rendering still works

4. If MLT works correctly, apply to all Martin sources
   If issues found, document them and revert to MVT

This is experimental — keep MVT as fallback. Do not break existing functionality.
Build with `npx next build` to verify zero errors.

Phase 2D: mvt-rs Evaluation (Future — Multi-Tenant)

Impact: Built-in auth, admin UI, per-layer access control. Effort: 1-2 days for evaluation + migration.

Implementation Prompt

Evaluate mvt-rs as a replacement for Martin in ArchiTools Geoportal for multi-tenant deployment.

Context:
- Current: Martin v1.4.0 serving 9 PostGIS sources (views in EPSG:3844)
- Martin config baked into image via martin.Dockerfile
- Goal: Expose geoportal to external clients with per-layer access control
- mvt-rs repo: https://github.com/mvt-proj/mvt-rs (v0.16.2+, Rust, Salvo framework)

Requirements:

1. Deploy mvt-rs as a Docker container alongside Martin (don't replace yet)
   - Use same DATABASE_URL
   - Map to different port (e.g., 3011)

2. Configure mvt-rs with equivalent layers to martin.yaml:
   - gis_uats_z0/z5/z8/z12, gis_administrativ, gis_terenuri, gis_cladiri
   - gis_terenuri_status, gis_cladiri_status
   - All with EPSG:3844, explicit properties

3. Test:
   - Do all properties appear in MVT output? (especially cadastral_ref on gis_cladiri)
   - Performance comparison: curl timing for 10 representative tiles vs Martin
   - Admin UI: create test user, assign layer permissions
   - Cache: configure disk cache, measure cold vs warm tile times

4. Document findings:
   - Property inclusion: pass/fail per layer
   - Performance delta vs Martin
   - Admin UI capabilities and limitations
   - Missing features vs Martin (PMTiles, MLT, etc.)

5. Decision matrix: when to switch from Martin to mvt-rs

Do NOT modify the production Martin setup. This is a parallel evaluation only.

---

Key Technical Details

Martin v1.4.0 Deployment Architecture

Gitea repo (martin.yaml + martin.Dockerfile)
  -> Portainer CE builds custom image: FROM martin:1.4.0, COPY martin.yaml
  -> Container starts with --config /config/martin.yaml
  -> Reads DATABASE_URL from environment
  -> Serves 9 PostGIS view sources on port 3000
  -> Host maps 3010:3000
  -> Traefik proxies tools.beletage.ro/tiles -> host:3010

Critical: Do NOT use volume mounts for config files in Portainer CE stacks. Always bake configs into custom images via Dockerfile COPY.

Martin Config (validated compatible v0.15 through v1.4)

The martin.yaml at project root defines 9 sources with explicit properties. Config format unchanged from v0.15 to v1.4 — no migration needed.

Key config features used:

• auto_publish: false — only explicitly listed sources are served
• default_srid: 3844 — all sources use Stereo70
• properties: map per source — explicit column name + PostgreSQL type
• minzoom/maxzoom per source — controls tile generation range
• bounds: [20.2, 43.5, 30.0, 48.3] — approximate Romania extent

Docker Image Tag Convention

Martin changed tag format at v1.0:

• Pre-1.0: ghcr.io/maplibre/martin:v0.15.0 (with v prefix)
• Post-1.0: ghcr.io/maplibre/martin:1.4.0 (no v prefix)
• Also available: latest, nightly

PostGIS View Chain

GisFeature table (Prisma) -> gis_features view -> gis_terenuri / gis_cladiri / gis_administrativ
                                                -> gis_terenuri_status / gis_cladiri_status (with JOINs)
GisUat table -> gis_uats_z0/z5/z8/z12 (with ST_SimplifyPreserveTopology)

MapLibre Layer Architecture

Sources (Martin):     gis_uats_z0, z5, z8, z12, administrativ, terenuri, cladiri
Layers per source:    fill + line + label (where applicable)
Selection:            Separate highlight layers on terenuri source
Drawing:              GeoJSON source for freehand/rect polygon
Building labels:      cladiriLabel layer, cadastral_ref at minzoom 16

---

Deployment Pitfalls (Discovered During Implementation)

1. Portainer CE does not expose repo files to containers at runtime. Volume mounts like ./file.conf:/etc/file.conf:ro fail silently — Docker creates an empty directory. Always bake config files into custom images via Dockerfile COPY.

2. Martin Docker tag format change at v1.0. v1.4.0 does not exist, 1.4.0 does. Always check ghcr.io/maplibre/martin for actual tags.

3. Martin logs UNKNOWN GEOMETRY TYPE for PostGIS views. This is normal — nested views don't register geometry types in geometry_columns. Does not affect functionality.

4. Martin auto-discovery mode is unreliable for property inclusion. Always use explicit config with auto_publish: false and per-source properties: definitions.

5. Martin caches source schema at startup. After PostGIS view DDL changes (e.g., adding columns to gis_features), Martin must be restarted to pick up new columns.

---

References

• Martin Documentation
• Martin Releases
• Martin Container Registry
• Vector Tiles Benchmark (Rechsteiner 2025)
• PMTiles Specification
• tippecanoe (Felt)
• MLT Format Announcement
• mvt-rs
• pg_tileserv
• Tegola
• Serving Vector Tiles Fast (Spatialists)