Passer au contenu principal

Déployer instance OverPass API avec Docker

Documentation d'utilisation du service Overpass API (image b1tw153/overpass-api) déployé via Docker Compose, avec extrait France.

Architecture

Le docker-compose.yml définit deux services :

Service Rôle Usage
overpass-init Télécharge et importe l'extrait OSM (une seule fois) docker compose run --rm overpass-init
overpass Sert l'API + applique les diffs minute par minute docker compose up -d overpass

Les deux services partagent les mêmes volumes Docker externes et nommés explicitement (overpass-db, overpass-backup), ce qui garantit qu'ils pointent toujours sur les mêmes données, peu importe le dossier depuis lequel les commandes sont lancées.

Point important : les volumes sont déclarés en external: true. Cela signifie qu'ils doivent exister avant de lancer docker compose up - Compose ne les créera pas automatiquement.

Fichier docker-compose.yml

services:
  # ----------------------------------------------------------------------
  # Service d'INITIALISATION (à lancer une seule fois, en amont)
  # Télécharge + importe l'extrait France, puis s'arrête (--rm).
  # Usage : docker compose run --rm overpass-init
  # ----------------------------------------------------------------------
  overpass-init:
    image: b1tw153/overpass-api:latest
    container_name: overpass-init
    entrypoint: /opt/overpass/bin/import_osm_data.sh
    command:
      - --diff-url=https://download.openstreetmap.fr/replication/europe/france/minute/
      - --data-source=https://download.geofabrik.de/europe/france-latest.osm.pbf
      - --meta=yes
    volumes:
      - overpass-db:/opt/overpass/db
    profiles:
      - init

  # ----------------------------------------------------------------------
  # Service PRINCIPAL (utilisation normale au quotidien)
  # Usage : docker compose up -d overpass
  # ----------------------------------------------------------------------
  overpass:
    image: b1tw153/overpass-api:latest
    container_name: overpass
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - OVERPASS_REPLICATE_ID=auto
      - OVERPASS_DIFF_URL=https://download.openstreetmap.fr/replication/europe/france/minute/
      - OVERPASS_UPDATE_FREQUENCY=60
      - OVERPASS_META_MODE=yes
      - OVERPASS_AREAS=yes
    volumes:
      - overpass-db:/opt/overpass/db
      - overpass-backup:/opt/overpass/backup
    mem_limit: 8g
    stop_grace_period: 5m

volumes:
  overpass-db:
    name: overpass-db
    external: true
  overpass-backup:
    name: overpass-backup
    external: true

Prérequis

  • Docker + Docker Compose v2
  • Espace disque suffisant sur le volume Docker (compter large pour un extrait France + croissance dans le temps - prévoir plusieurs dizaines de Gio minimum)

Premier déploiement

1. Créer les volumes externes

docker volume create overpass-db
docker volume create overpass-backup

2. Lancer l'import initial

docker compose run --rm overpass-init

Ce que fait ce service :

  • télécharge l'extrait france-latest.osm.pbf depuis Geofabrik
  • importe les données de base (nodes/ways/relations) avec métadonnées (--meta=yes)
  • initialise le point de reprise pour la réplication (--diff-url)

⏱ Durée estimée : plusieurs heures selon la machine (CPU/disque). Le conteneur se supprime automatiquement à la fin (--rm), les données restent dans le volume overpass-db.

Pour suivre la progression :

docker compose logs -f overpass-init

3. Démarrer le service principal

Une fois l'import terminé :

docker compose up -d overpass

Vérifier que ça démarre sans erreur (en particulier l'absence de Database directory does not contain required base files) :

docker compose logs -f overpass

Utilisation au quotidien

Action Commande
Démarrer docker compose up -d overpass
Arrêter proprement docker compose stop overpass
Voir les logs en direct docker compose logs -f overpass
Redémarrer docker compose restart overpass
Statut docker compose ps

⚠️ Ne jamais faire docker compose down -v - cela supprimerait aussi les volumes (et donc toutes les données importées). Un simple docker compose down (sans -v) est sans danger pour les données.

Le service applique automatiquement les diffs OSM toutes les OVERPASS_UPDATE_FREQUENCY secondes (actuellement 60s) via OVERPASS_DIFF_URL. Aucune action manuelle n'est nécessaire pour rester à jour.

Tester l'API

curl -sg 'http://localhost:8080/api/interpreter' --data-urlencode 'data=[out:json];out count;'

(adapter le port si vous exposez le service sur un port différent dans ports:)

Une requête géographique simple (mairie de Toulouse) :

curl -sg 'http://localhost:8080/api/interpreter' --data-urlencode 'data=
[out:json][timeout:25];
node["amenity"="townhall"]["name"~"Toulouse"];
out center;
'

Tester les areas

Les areas (utilisées par exemple pour area["name"="..."]->.a;) sont calculées en arrière-plan après l'import initial et peuvent prendre plusieurs heures à être disponibles, même une fois l'import de base terminé.

Vérifier si le calcul a produit des résultats

curl -sg 'http://localhost:8080/api/interpreter' --data-urlencode 'data=[out:json];out count;' | jq

La présence du champ osm3s.timestamp_areas_base indique qu'au moins un cycle de calcul des areas s'est terminé. Son absence = pas encore de areas disponibles.

Tester une area précise

L'ID d'une area = ID de la relation OSM + 3600000000 :

curl -sg 'http://localhost:8080/api/interpreter' --data-urlencode 'data=
[out:json][timeout:25];
area(3600035738);
out;
' | jq

(exemple : 3600035738 = relation Toulouse, admin_level=8)

Sauvegardes

Pour activer les sauvegardes automatiques (désactivées par défaut - voir le log INFO: Specify OVERPASS_BACKUP_TIME or OVERPASS_BACKUP_DAY to enable backups), ajouter dans environment: du service overpass :

- OVERPASS_BACKUP_TIME=03:00
# et/ou
- OVERPASS_BACKUP_DAY=SUN

Les sauvegardes sont écrites dans le volume overpass-backup (déjà monté). La base est temporairement mise en pause pendant la copie.

Fichiers de référence

  • Image Docker : b1tw153/overpass-api
  • Dépôt source : b1tw153/Overpass-API
  • Documentation Overpass QL : https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL
  • Extraits France : https://download.geofabrik.de/europe/france.html
  • Réplication France : https://download.openstreetmap.fr/replication/europe/france/minute/

Aucun commentaire à afficher

Retour en haut