# Cartographie autonome premium avec OpenMapTiles

Ce guide formalise le socle cartographique auto-heberge du portail pour obtenir une carte :

- rapide
- lisible
- premium
- autonome
- exploitable dans le public comme dans l'admin

## Architecture retenue

Le portail repose sur trois briques distinctes :

1. `OpenMapTiles Server` sur le VPS pour servir :
   - le `TileJSON`
   - les tuiles vectorielles `.pbf`
   - les glyphes
   - les sprites
   - le style serveur de base `OSM OpenMapTiles`
2. `MapLibre` dans le portail pour afficher la carte dans les vues publiques et admin
3. `Maputnik` pour personnaliser les styles JSON sans casser le serveur de tuiles

## Emplacements actuels sur le VPS

- application prod : `/home/ubuntu/portail-associations`
- application preprod : `/home/ubuntu/portail-associations-preprod`
- serveur OpenMapTiles : `/home/ubuntu/openmaptiles-guyane`

Conteneur constate :

- `openmaptiles-guyane-tileserver-gl-1`

## URLs utiles

### Style serveur de base

- [OSM OpenMapTiles](https://www.portail-association973.com/map-tiles/styles/OSM%20OpenMapTiles/style.json)

### Sources auto-hebergees

- [TileJSON](https://www.portail-association973.com/data/openmaptiles.json)
- glyphes : `https://www.portail-association973.com/fonts/{fontstack}/{range}.pbf`
- sprites serveur : `https://www.portail-association973.com/styles/OSM%20OpenMapTiles/sprite`

### Styles portail

- [OSM Bright CCDS](https://www.portail-association973.com/map-styles/openmaptiles-positron/style.json)
- [OSM Bright CCDS Admin Dense](https://www.portail-association973.com/map-styles/openmaptiles-positron-admin/style.json)
- `OSM Basic auto-heberge` = style serveur OpenMapTiles

## Contraintes utiles a garder

Pour rester stable en exploitation comme en local :

- le style portail `OSM Bright CCDS` doit utiliser un `sprite` absolu
- les `glyphs` doivent pointer vers `https://www.portail-association973.com/fonts/{fontstack}/{range}.pbf`
- les piles de polices doivent rester compatibles avec ce que sert vraiment OpenMapTiles

Piles recommandees :

- texte courant carte : `Noto Sans Regular`
- italique carte : `Noto Sans Italic`
- compteurs / clusters : `Open Sans Bold`

Eviter :

- `Metropolis *`
- `Arial Unicode MS Bold`
- les piles de plusieurs polices non supportees par le serveur de glyphes

## Ordre d'execution recommande

1. verifier le serveur OpenMapTiles
2. verifier ou regnerer les tuiles Guyane
3. activer le style cible dans l'admin
4. ajuster le rendu avec Maputnik
5. verifier la carte publique et la carte admin
6. affiner ensuite l'ambiance premium dans Apparence

## 1. Verifier le serveur OpenMapTiles

Depuis le poste local :

```bash
./scripts/check-openmaptiles-vps.sh
```

Ce script controle :

- le conteneur Docker
- le style JSON serveur
- le TileJSON
- les glyphes

### Healthcheck recommande

Le conteneur `tileserver-gl` peut rester `unhealthy` si son healthcheck interne vise encore `localhost:8080/health` alors que le serveur tourne sur un autre port expose par la stack, par exemple `8091`.

Le healthcheck doit donc viser le port effectif :

```yaml
healthcheck:
  test:
    [
      "CMD-SHELL",
      "node -e \"require('http').get('http://localhost:${TPORT:-8080}/health',res=>process.exit(res.statusCode===200?0:1)).on('error',()=>process.exit(1))\"",
    ]
  interval: 30s
  timeout: 5s
  retries: 5
  start_period: 20s
```

## 2. Generer ou reutiliser les tuiles Guyane

Le depot serveur utilise deja le projet OpenMapTiles officiel dans :

`/home/ubuntu/openmaptiles-guyane`

### Relancer le serveur de tuiles

```bash
ssh ovh-vps 'cd /home/ubuntu/openmaptiles-guyane && docker compose up -d tileserver-gl'
```

### Ouvrir Maputnik

```bash
ssh ovh-vps 'cd /home/ubuntu/openmaptiles-guyane && docker compose up -d maputnik_editor'
```

Maputnik sera ensuite accessible sur le port expose par le serveur si un proxy ou un tunnel SSH est mis en place.

### Regenerer les tuiles

Commande lourde, a lancer seulement si besoin de regenerer la base :

```bash
ssh ovh-vps 'cd /home/ubuntu/openmaptiles-guyane && docker compose run --rm generate-vectortiles'
```

## 3. Activer un style dans le portail

Dans `Administration > Référentiel associations > Carte OpenStreetMap / MapLibre`, utiliser l'un des presets :

- `OSM Bright auto-heberge` : rendu clair premium, lisible pour l'annuaire
- `OSM Basic auto-heberge` : style serveur brut, plus neutre

## 4. Personnaliser avec Maputnik

Le flux recommande est :

1. partir du style `openmaptiles-positron`
2. l'ouvrir dans Maputnik
3. ajuster :
   - couleurs d'eau
   - verts
   - routes
   - contrastes
   - labels
4. reexporter le `style.json`
5. remplacer le fichier du portail :

`client/public/map-styles/openmaptiles-positron/style.json`

Le style portail doit toujours pointer vers :

- `https://www.portail-association973.com/data/openmaptiles.json`
- `https://www.portail-association973.com/fonts/{fontstack}/{range}.pbf`

### Direction visuelle premium retenue

Pour la Guyane, la passe visuelle vise un rendu plus institutionnel et plus territorial :

- fond general plus chaud et plus respirant
- eau plus lisible, avec fleuves et criques mieux marques
- vegetation plus douce, sans saturer la carte
- zones urbanisees legerement rechauffees pour mieux separer le bati du fond
- routes principales plus visibles avec une hierarchie creme / sable / ocre
- labels de communes et repères plus contrastes, avec halos plus propres pour le mobile

Objectif UX :

- lecture immediate des communes et des axes utiles
- rendu plus premium, sans basculer dans une carte decorative
- coherence avec le portail, ses cards et ses panneaux

### Variante admin dense

Une variante plus sobre est aussi disponible pour le pilotage :

- labels legerement plus petits
- hierarchie de communes plus resserree
- routes et repères plus discrets
- lecture plus compacte pour les vues admin denses

## 5. Ambiance premium dans le portail

Le fond immersif et l'opacite doivent rester dans le portail, pas dans le style cartographique lui-meme.

Bonne pratique :

- la carte reste nette et lisible
- les panneaux et cards restent opaques
- l'ambiance premium se gere via `Apparence`

## 6. Validation finale

Verifier au minimum :

- carte publique
- annuaire public
- carte admin
- filtres
- popups
- mobile
- desktop

## Decision retenue

Le portail garde deux niveaux propres :

- `Fond de carte` : OpenMapTiles + style MapLibre
- `Ambiance premium` : Apparence + fond + opacite + habillage du portail

Cela evite de melanger le rendu cartographique metier avec le rendu decoratif global.