wiki/Catalogue-Self-Hosted/apps/app-docker-staticmaps.md

---
title: docker-staticmaps
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, development, cartography, static-maps, docker, geo]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Development, https://github.com/StephanGeorg/docker-staticmaps]
---

# 💻 docker-staticmaps

> **Générateur de cartes statiques dans Docker** — créez des images PNG/JPG de cartes (OpenStreetMap, tiles personnalisées) à partir de coordonnées GPS, polylines, polygones et marqueurs, sans serveur de tuiles dynamique.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [github.com/StephanGeorg/docker-staticmaps](https://github.com/StephanGeorg/docker-staticmaps) |
| **GitHub** | [StephanGeorg/docker-staticmaps](https://github.com/StephanGeorg/docker-staticmaps) |
| **License** | MIT |
| **Langage** | Go (basé sur [staticmaps](https://github.com/StephanGeorg/staticmaps)) |
| **Étoiles GitHub** | 125 ⭐ |
| **Catégorie** | Development, Cartographie / Geo |
| **Référence** | [selfh.st Development](https://selfh.st/apps/?tag=Development) |

## 📝 Description

**docker-staticmaps** est un **wrapper Docker autour de la lib Go `staticmaps` de Stephan Georg** : il permet de **générer des images statiques de cartes** (PNG/JPG) à partir de coordonnées GPS, en assemblant des **tuiles OpenStreetMap (ou autres serveurs de tuiles)** et en y superposant des **polylines, polygones, cercles, marqueurs, textes**.

Le besoin typique : on veut afficher une carte dans un email, un PDF généré côté serveur, un rapport, une notification push, une vignette de partage social — partout où un **Leaflet/Mapbox interactif ne passe pas**. Les services comme **Mapbox Static API** ou **Google Static Maps API** facturent au 1000 requêtes et imposent leurs serveurs. `docker-staticmaps` assemble les tuiles **chez vous** en utilisant un tile server OSM (TileServer GL, OpenStreetMap public, ou votre propre instance).

L'outil est **exposé comme une API HTTP minimaliste** : on envoie une requête `GET /map?lat=48.85&lon=2.35&zoom=12&width=600&height=400&markers=...` et on récupère un PNG. Il peut être **appelé depuis n8n, Node-RED, un cron, un script Python** ou n'importe quel générateur de PDF. La lib Go sous-jacente gère le **cache de tuiles** localement (LRU), la **projection Web Mercator**, le **rendu antialiasé** et les **formats vectoriels GPX/KML/GeoJSON**.

**Cas d'usage** : générer une carte de la dernière position d'une flotte de véhicules dans un email, intégrer une carte dans un rapport PDF, créer des vignettes OG/Twitter Cards avec position, dashboards Grafana avec carte statique, génération batch de cartes pour un atlas.

## 🚀 Installation

### Via Docker (recommandé)

```yaml
# docker-compose.yml
version: '3.8'
services:
  staticmaps:
    image: ghcr.io/stephanhgeorg/docker-staticmaps:latest
    container_name: staticmaps
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      TILE_URL: "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
      TILE_CACHE_DIR: "/cache/tiles"
      DEFAULT_ZOOM: "12"
      DEFAULT_WIDTH: "800"
      DEFAULT_HEIGHT: "600"
      USER_AGENT: "selfh-staticmaps/1.0 (contact@example.com)"
      CACHE_TTL: "168h"     # 1 semaine
    volumes:
      - sm_cache:/cache/tiles
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.sm.rule=Host(`maps.example.com`)"
      - "traefik.http.routers.sm.entrypoints=websecure"
      - "traefik.http.routers.sm.tls.certresolver=letsencrypt"

volumes:
  sm_cache:
```

### Utilisation via curl (une fois démarré)

```bash
# Carte simple centrée sur Paris
curl -o paris.png "https://maps.example.com/map?lat=48.85&lon=2.35&zoom=12"

# Avec marqueur, polyline et taille custom
curl -o track.png "https://maps.example.com/map?\
  bbox=-0.5,48.8,0.2,49.0&\
  markers=48.85,2.35,red&\
  polyline=48.85,2.35|48.86,2.36|48.87,2.37|color:blue,width:3&\
  width=1200&height=800"

# Trace GPX
curl -o ride.png "https://maps.example.com/map?gpx=https://example.com/ride.gpx"
```

### Installation manuelle

```bash
git clone https://github.com/StephanGeorg/docker-staticmaps.git
cd docker-staticmaps
go build -o staticmaps ./cmd
./staticmaps --config config.yaml
```

## ⚙️ Configuration

1. **`TILE_URL`** : URL du serveur de tuiles. Par défaut OSM public (attention à la **politique d'usage** : pas plus de quelques req/s, User-Agent obligatoire).
2. **Tile server privé** : pour de la prod, monter un [[app-tileserver-gl]] ou un proxy cached devant OSM pour respecter la tile usage policy.
3. **User-Agent** : **obligatoire** pour OSM public (sinon ban IP) — un contact email valide dans le User-Agent.
4. **Cache** : `sm_cache` volume monté sur `/cache/tiles` — taille à surveiller (peut monter à plusieurs Go).
5. **Rate limiting** : activer un rate-limit Traefik sur `/map` pour éviter l'abus et le ban OSM.

## 🔗 Alternatives

- **Mapbox Static API** — Excellente qualité, mais cloud only, facturé au 1000 requêtes.
- **Google Static Maps API** — Simple, mais très cher, RGPD-hostile, et déprécié en 2025.
- **StaticMap (npm)** — Lib Node.js équivalente, à intégrer dans une API perso (plus de code).
- **Mapy.cz Static API** — Alternative tchèque, plan gratuit généreux.
- **TileServer GL + screenshot** — Plus complet (rendu vectoriel) mais lourd (Node + GL native deps).

## 🔒 Sécurité

- 🔐 **HTTPS obligatoire** via [[app-traefik]] : les coordonnées GPS dans les URLs sont sensibles (géolocalisation d'utilisateurs).
- 🛡️ **Rate limiting strict** : OSM public bannit les IPs qui abusent (politique : 1 worker par site, pas plus de 2 req/s).
- 🛡️ **Tile server interne** : pour un usage sérieux, monter un tile server (TileServer GL) en interne et le pointer via `TILE_URL=http://internal-tiles/...`.
- 🛡️ **Validation des inputs** : limiter `zoom` (1-19) et `width/height` (max 2000x2000) pour éviter l'abus (DoS via génération de cartes énormes).
- 🛡️ **Pas d'auth intégrée** : placer derrière un [[app-traefik]] avec BasicAuth si l'API doit être restreinte.
- 🛡️ **Logs** : attention à ne pas logger les URLs complètes si elles contiennent des positions sensibles (géofencing privé).

## 📚 Ressources

- [GitHub StephanGeorg/docker-staticmaps](https://github.com/StephanGeorg/docker-staticmaps)
- [Lib Go staticmaps](https://github.com/StephanGeorg/staticmaps)
- [Selfh.st — Development](https://selfh.st/apps/?tag=Development)
- [OpenStreetMap Tile Usage Policy](https://operations.osmfoundation.org/policies/tiles/)
- [Mapbox Static API (référence)](https://docs.mapbox.com/api/maps/static-images/)

## 🔗 Pages Liées

- [[cat-development]] — Catégorie Development
- [[app-traefik]] — Reverse proxy HTTPS
- [[securisation-home-lab]] — Bonnes pratiques de sécurité
- [[recettes-docker-compose]] — Templates Docker Compose