docs(geoportal): update evaluation + skills with deployment lessons learned
- Portainer CE volume mount pitfall (silent empty directory creation) - Martin Docker tag format change at v1.0 (v prefix dropped) - UNKNOWN GEOMETRY TYPE log is normal for views - Bake-into-image pattern for config files in Portainer deployments - Updated all implementation prompts with Portainer-safe instructions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -65,11 +65,18 @@ postgres:
|
||||
area: float8
|
||||
```
|
||||
|
||||
### Docker image tags
|
||||
|
||||
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)
|
||||
|
||||
### Docker deployment
|
||||
|
||||
**If your orchestrator has access to the full repo** (docker-compose CLI, Docker Swarm with repo checkout):
|
||||
```yaml
|
||||
martin:
|
||||
image: ghcr.io/maplibre/martin:v1.4.0
|
||||
image: ghcr.io/maplibre/martin:1.4.0
|
||||
command: ["--config", "/config/martin.yaml"]
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://user:pass@host:5432/db
|
||||
@@ -79,6 +86,28 @@ martin:
|
||||
- "3010:3000"
|
||||
```
|
||||
|
||||
**If using Portainer CE or any system that only sees docker-compose.yml** (not full repo):
|
||||
Volume mounts for repo files fail silently — Docker creates an empty directory instead.
|
||||
Bake config into a custom image:
|
||||
|
||||
```dockerfile
|
||||
# martin.Dockerfile
|
||||
FROM ghcr.io/maplibre/martin:1.4.0
|
||||
COPY martin.yaml /config/martin.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
martin:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: martin.Dockerfile
|
||||
command: ["--config", "/config/martin.yaml"]
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://user:pass@host:5432/db
|
||||
ports:
|
||||
- "3010:3000"
|
||||
```
|
||||
|
||||
### Custom SRID handling
|
||||
|
||||
Martin handles non-4326/3857 SRIDs natively. Set `default_srid` globally or `srid` per source. Martin reprojects to Web Mercator (3857) internally for tile envelope calculations. Your PostGIS spatial indexes on the source SRID are used correctly.
|
||||
@@ -170,12 +199,15 @@ map.addSource('overview', {
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Martin auto-discovery drops properties** — always use explicit config with `auto_publish: false`
|
||||
2. **Nested views lose SRID metadata** — cast geometry: `geom::geometry(Geometry, 3844)`
|
||||
3. **GisUat.geometry is huge** — always `select` to exclude in list queries
|
||||
4. **Low-zoom tiles scan entire dataset** — use zoom-dependent simplified views
|
||||
5. **No tile cache by default** — add nginx/Varnish in front of any tile server
|
||||
6. **tippecanoe requires WGS84** — reproject from custom SRID before generating PMTiles
|
||||
7. **PMTiles not incrementally updatable** — full rebuild required on data change
|
||||
8. **Tegola doesn't support custom SRIDs** — only 3857/4326, requires ST_Transform everywhere
|
||||
9. **pg_tileserv `ST_Estimated_Extent` fails on views** — use materialized views or function layers
|
||||
10. **Martin caches source schema at startup** — restart after view DDL changes
|
||||
2. **Martin Docker tag format changed at v1.0** — `v0.15.0` (with v) but `1.4.0` (without v). Check actual tags at ghcr.io.
|
||||
3. **Portainer CE volume mounts fail silently** — Docker creates empty directory instead of file. Bake configs into images via Dockerfile COPY.
|
||||
4. **Martin logs `UNKNOWN GEOMETRY TYPE` for views** — normal for nested views, does not affect tile generation
|
||||
5. **Nested views lose SRID metadata** — cast geometry: `geom::geometry(Geometry, 3844)`
|
||||
6. **GisUat.geometry is huge** — always `select` to exclude in list queries
|
||||
7. **Low-zoom tiles scan entire dataset** — use zoom-dependent simplified views
|
||||
8. **No tile cache by default** — add nginx/Varnish in front of any tile server
|
||||
9. **tippecanoe requires WGS84** — reproject from custom SRID before generating PMTiles
|
||||
10. **PMTiles not incrementally updatable** — full rebuild required on data change
|
||||
11. **Tegola doesn't support custom SRIDs** — only 3857/4326, requires ST_Transform everywhere
|
||||
12. **pg_tileserv `ST_Estimated_Extent` fails on views** — use materialized views or function layers
|
||||
13. **Martin caches source schema at startup** — restart after view DDL changes
|
||||
|
||||
Reference in New Issue
Block a user