Contribuer au développement de ProjetDuMois.fr

Dépendances

NodeJS >= 12.9
Outils Bash : curl, awk, grep, sed, xsltproc, bc
PostgreSQL >= 10
Python 3
Osmium > 1.10
osmctools
Imposm >= 3
pg_tileserv
Dépendances de sendfile_osm_oauth_protector

Compilation osmium

ProjetDuMois a besoin d'une version récente de osmium puisqu'il tire parti des nouvelles fonctions tags-filter. Peu de distributions linux ont les dernières versions disponibles et vous aurez surement besoin de compiler osmium vous-même.

Voir les consignes sur le README officiel.

Les paquets suivants pourront être utiles pour cela

build-essential
cmake
zlib1g-dev
libbz2-dev
liblz4-dev
libboost-dev
libboost-program-options-dev

Débuter

git clone https://github.com/vdct/ProjetDuMois.git
cd ProjetDuMois
git submodule update --init

Configuration générale

La configuration générale de l'outil est à renseigner dans config.json. Un modèle est proposé dans le fichier config.example.json. Les paramètres sont les suivants :

OSM_USER : nom d'utilisateur OpenStreetMap pour la récupération de l'historique des modifications avec métadonnées
OSM_PASS : mot de passe associé au compte utilisateur OSM
OSM_API_KEY : clé d'API OSM
OSM_API_SECRET : secret lié à la clé d'API OSM
OSH_PBF_URL : URL du fichier OSH.PBF (historique et métadonnées, exemple https://osm-internal.download.geofabrik.de/europe/france/reunion-internal.osh.pbf)
DB_USE_IMPOSM_UPDATE : Active ou désactive l'intégration d'imposm3 (permet d'utiliser une base existante et tenue à jour par d'autres moyens, par défaut true)
WORK_DIR : dossier de téléchargement et stockage temporaire (doit pouvoir contenir le fichier OSH PBF, exemple /tmp/pdm)
OSM_URL : instance OpenStreetMap à utiliser (exemple https://www.openstreetmap.org)
JOSM_REMOTE_URL : adresse du serveur JOSM à contacter (exemple http://localhost:8111)
OSMOSE_URL : instance Osmose à utiliser (exemple https://osmose.openstreetmap.fr)
NOMINATIM_URL : instance de Nominatim à utiliser (exemple https://nominatim.openstreetmap.org)
MAPILLARY_URL : instance Mapillary à utiliser (exemple https://www.mapillary.com)
MAPILLARY_API_KEY: clé d'API Mapillary (peut être créée ici)
REPOSITORY_URL : URL du dépôt du logiciel (exemple https://github.com/vdct/ProjetDuMois)
MAPBOX_STYLE : URL d'un style compatible avec Mapbox GL (exemple https://tile-vect.openstreetmap.fr/styles/liberty/style.json)
PDM_TILES_URL : URL d'accès au service pg_tileserv, qui met à disposition les couches dans votre base de données
GEOJSON_BOUNDS : objet de type Geometry (polygone ou multipolygone) en GeoJSON délimitant la zone où rechercher des notes OSM
MAINTENANCE_MODE: option pour afficher une page spéciale sur le site indiquant qu'il est en cours de maintenance (valeur true pour activer)

Connexion à Postgresql

Pour se connecter à Postgresql, une variable d'environement DB_URL est attendue avec une chaine conninfo pour disposer des informations nécessaires. Ceci est valable quelle que soit la solution retenue, docker ou locale.

export DB_URL="postgres://user:password@host:5432/database"

Reportez-vous au chapitre 33.1.1 du guide postgresql.

Configuration des projets

Chaque projet est défini via un sous-répertoire de projects. Chaque sous-répertoire doit contenir les fichiers suivants :

info.json : métadonnées du projet
howto.md : descriptif des tâches à réaliser au format Markdown (utiliser les niveaux de titres >= 3)
contribs.sql : Script SQL contenant des requêtes UPDATE sur la table pdm_changes, attribuant des classes de contribution à certains changements donnant droit à des points

Les propriétés dans info.json sont les suivantes :

id : identifiant de la mission (caractères autorisés : A-Z, 0-9, _ et -)
title : nom de la mission (assez court)
start_date : date de début de la mission (format AAAA-MM-JJ)
end_date : date de fin de la mission (format AAAA-MM-JJ)
summary : résumé de la mission
links : définition des URL pour les liens vers des pages tierces (wiki OSM)
database.osmium_tag_filter : filtre Osmium sur les tags à appliquer pour ne conserver que les objets OSM pertinents (par exemple nwr/*:covid19, syntaxe décrite ici). Il est possible d'enchaîner plusieurs filtres par & et en répétant l'indication de primitive à chaque niveau. Seul le dernier filtre est utilisé pour catégoriser les décomptes par osmium.
database.imposm : configuration pour l'import des données actualisées d'OSM (types pour les types de géométrie à prendre en compte, mapping pour les attributs, voir la documentation Imposm pour le format de ces champs)
database.compare : configuration pour la recherche d'objets OpenStreetMap à comparer, suit le format de database.imposm avec une propriété supplémentaire radius (rayon de rapprochement en mètres)
datasources : liste des sources de données qui apparaissent sur la page (voir ci-dessous)
statistics : configuration de l'affichage des statistiques sur la page du projet
statistics.count : activer le comptage des objets dans OSM
statistics.feature_name : nom à afficher à l'utilisateur pour ces objets
statistics.osmose_tasks : nom des tâches accomplies via Osmose
statistics.points : configuration des points obtenus selon le type de contribution (en lien avec contribs.sql)
editors : configuration spécifique à chaque éditeur OSM. Pour ProjetDuMois, les informations sont disponibles ci-dessous. Pour iD, il est possible d'utiliser les paramètres listés ici.

Temporalité des projets

Il est possible de définir des projets se déroulant aux mêmes dates. Le script project:update ne rafraichira que les projets en cours.

Se passer d'imposm3

Il est possible de ne pas utiliser imposm3 et de se connecter à une base de données pourvue des données nécessaires. Il faudra s'assurer qu'elle est tenue à jour toutes les heures minimum pour les besoins de PdM.

Dans le cas où imposm3 serait désactivé, il faudra produire des vues matérialisées pour chaque projet configurés appelées pdm_project_${project_id}, avec la structure suivante :

osm_id BIGINT,
name VARCHAR(255)
tags json
geom GEOMETRY

Optionellement, si le mode compare est activé dans un projet donné, une vue supplémentaire appelée pdm_project_${project_id}_compare conforme à ce qui doit être comparé est nécessaire. Elle a la même structure que ci-dessus.

Au-delà de ces tables, il est nécessaire d'avoir une table pdm_boundary contenant le découpage administratif de la zone (niveaux administratifs 4, 6 et 8) et ayant cette structure :

id INT
osm_id BIGINT
name VARCHAR
admin_level INT
tags HSTORE
geom GEOMETRY(Geometry, 3857)
centre GEOMETRY(Point, 3857)

La colonne centre est comprise comme étant un point compris dans le périmètre de la limite (vous pouvez utiliser ST_PointOnSurface).

Créer des indexes sur les colonnes osm_id, tags, geom et centre peut être utile suivant la population d'objets touchée par un projet donné.

PdM va automatiquement créer une table pdm_boundary_subdivide en utilisant ST_Subdivide pour faciliter le calcul d'intersection entre les objets du projet et le zonage administratif.

Sources de tuiles

Plusieurs sources de tuiles sont mobilisables, et sont à faire apparaître dans le champ datasources du fichier info.json.

Osmose

Osmose est un outil d'analyse qualité et d'aide à l'intégration de données ouvertes. Les propriétés à renseigner sont les suivantes :

source (obligatoire osmose): type de source
item : numéro d'item (code à quatre chiffres)
class (optionnel) : numéro de classe (code à plusieurs chiffres)
country (optionnel) : motif de nom de pays Osmose (exemple france*)
name : nom à faire apparaître à l'utilisateur
subtitles (optionnel) : objet clé > valeur pour remplacer les sous-titres des signalements Osmose (recherche par motif)
buttons : libellé à faire apparaître sur les boutons d'édition (exemple { "done": "C'est fait", "false": "Rien ici" })
minzoom (défaut 7): Niveau de zoom minimum au delà duquel la couche est visible
maxzoom (défaut 18): Niveau de zoom maximal au delà duquel la couche n'est plus visible
tiles (défaut) : Liste d'URL TMS

Notes OSM

Les notes OpenStreetMap sont une méthode simple pour envoyer des commentaires textuels par dessus la carte, et faciliter la contribution par des publics novices. Les propriétés à renseigner sont les suivantes :

source (obligatoire notes): type de source
name : nom à faire apparaître à l'utilisateur
description : texte descriptif indiquant la méthode de résolution d'une note
terms : liste des termes à rechercher dans les notes (au singulier)
buttons : libellé à faire apparaître sur les boutons d'édition (exemple { "close": "C'est fait" })
data (défaut) : GeoJson de données de la couche

Objets OpenStreetMap

Les objets actuellement présents dans OpenStreetMap peuvent être affichés pour éviter les doublons et permettre leur édition. Les propriétés à renseigner sont les suivantes :

source (obligatoire osm): type de source
name : nom à faire apparaître à l'utilisateur
description : texte descriptif de l'objet affiché
minzoom (défaut 7) : Niveau de zoom minimum au delà duquel la couche est visible
maxzoom (défaut 14) : Niveau de zoom maximal au delà duquel la couche n'est plus visible
tiles (défaut) : Liste d'URL TMS
layers (défaut) : Liste des layers correspondant à tiles à utiliser

Cette source ne peut apparaître qu'une seule fois, et correspond aux objets recherchés dans les options database de info.json.

Objets OpenStreetMap pour comparaison

Des objets indirectement liés au projet mais pertinents pour la contribution peuvent également apparaître. Les propriétés à renseigner sont les suivantes :

source (obligatoire osm-compare) : type de source
name : nom à faire apparaître à l'utilisateur
description : texte descriptif de l'objet affiché
minzoom (défaut 9) : Niveau de zoom minimum au delà duquel la couche est visible
maxzoom (défaut 14) : Niveau de zoom maximal au delà duquel la couche n'est plus visible
tiles (défaut) : Liste d'URL TMS
layers (défaut) : Liste des layers correspondant à tiles à utiliser

Cette source ne peut apparaître qu'une seule fois, et correspond aux objets recherchés dans les options database.compare de info.json.

OpenStreetMap extra objects

Ces couches affichent des objets non pris en compte dans le périmètre du projet. Ils sont affichés pour informer les contributeurs que quelque chose de différent existe déjà à cet endroit. Les propriétés à fournir sont les suivantes :

source (obligatoire osm-extra) : type de source
name : nom à faire apparaître à l'utilisateur
description : texte descriptif de l'objet affiché
minzoom (défaut 9) : Niveau de zoom minimum au delà duquel la couche est visible
maxzoom (défaut 14) : Niveau de zoom maximal au delà duquel la couche n'est plus visible
tiles (défaut) : Liste d'URL TMS
layers (défaut) : Liste des layers correspondant à tiles à utiliser

Ces sources peuvent apparaitre autant de fois que nécessaire

Fonds raster

Des couches raster peuvent être ajoutées en fond de carte pour faciliter la contribution ou donner plus de contexte. Les propriétés suivantes doivent être définies :

source (obligatoire background): type de source
icon (défaut other): le symbole à afficher dans la légende (au choix aerial, thematic, picture, other)
name : nom à faire apparaître à l'utilisateur
tiles : Tableau d'URL TMS
attribution : Attribution à faire apparaitre sur la carte
minzoom (défaut 2) : Niveau de zoom minimum au delà duquel la couche est visible
maxzoom (défaut 19) : Niveau de zoom maximal au delà duquel la couche n'est plus visible
tileSize (défaut 256) : Taille d'une arrête de tuile en pixels

Ces sources doivent être déclarées dans l'ordre inverse d'apparition. La couche inférieure doit être donnée en premier.

Sources stats

Pour activer l'affichage de statistiques selon le découpage administratif, vous pouvez ajouter la couche ayant la définition suivante :

source (obligatoire stats): type de source
minzoom (défaut 2) : Niveau de zoom minimum au delà duquel la couche est visible
maxzoom (défaut 14) : Niveau de zoom maximal au delà duquel la couche n'est plus visible
tiles (défaut) : Tableau d'URL TMS
layers (défaut) : Liste des layers correspondant à tiles à utiliser

Éditeur intégré de Projet du Mois

La configuration des projets permets de personnaliser les champs disponibles dans l'éditeur intégré. La configuration s'exprime en JSON comme l'exemple suivant (ajouté dans l'objet editors du fichier config.json) :

"pdm": {
  "fields": [
    ... liste de champs...
  ],
  "title": {
    "add": "Libellé de l'action ajouter",
    "edit": "Libellé de l'action éditer"
  }
}

Les champs sont définis comme des objets JSON standards, ajouté au tableau fields ci-dessus.

Chaque type, à l'exception de hidden supporte les champ communs suivants :

name: Libellé du champ tel qu'affiché à l'utilisateur
help: Lien hypertexte pointant vers toute ressource appropriée d'aide pour ce champ
description: Un text plus long que le libellé qui apporte les détails nécessaire à propos de champ
optional: Un champ booléen false/true rendant respectivement le champ obligatoire ou non.

Attributs statiques ou externes

Il permet de définir des tags statiques ajoutés à tout objet créé avec l'éditeur. Il est possible dans la liste de tags d'ajouter une valeur * pour accepter toute valeur arrivant d'une source externe (par exemple les identifiants ref:FR:SIRET renseignés dans Osmose).

  { "type": "hidden", "tags": { "tag_1":"value_1", "tag_2":"value_2", "tag_3_externe": "*" } }

Champs classiques

Les champs textuels simples sont couverts par 3 types différents : text, number ou email. Ils produisent tous trois un champ texte standard muni des fonctions de validation appropriées.

  { "type": "text", "name": "Libellé", "tag": "tag_key", "optional": false },
  { "type": "number", "name": "Libellé", "tag": "tag_key", "optional": false },
  { "type": "email", "name": "Libellé", "tag": "tag_key", "optional": false }

Zone de texte

Une zone de texte plus ample pour saisir des valeurs plus conséquentes.

  { "type": "textarea", "name": "Libellé", "tag": "tag_key", "optional": false }

Listes de valeurs

Une liste de valeurs avec des entrées personnalisées pointant sur une clé OSM définie.

{ "type": "select", "name": "Libellé", "tag": "tag_key", "optional": false, "values": [
  { "v": "value_1", "l": "Value 1 label" },
  { "v": "value_2", "l": "Value 2 label" }
] }

On peut également faire en sorte que une valeur dans la liste renseigne plusieurs attributs OSM, par exemple :

{ "type": "select", "name": "Type", "tag": "_select1", "values": [
	{ "l": "Gendarmerie", "tags": { "name": "Gendarmerie nationale", "operator": "Gendarmerie nationale", "police:FR": "gendarmerie" } },
	{ "l": "Police nationale", "tags": { "name": "Police nationale", "operator": "Police nationale", "police:FR": "police" } },
	{ "l": "Police municipale", "tags": { "name": "Police municipale", "police:FR": "police_municipale" } }
] }

Dans le cas où plusieurs attributs sont renseignés, il est possible de forcer la suppression de certains tags avec un texte vide, par exemple pour gérer le cas où les objets sont dans plusieurs catégories :

{ "type": "select", "name": "Type de commerce", "tag": "_select1", "values": [
  { "l": "Agence d'assurance", "tags": { "shop": "", "office": "insurance" } },
  { "l": "Agence de voyages", "tags": { "shop": "travel_agency", "office": "" } }
] }

Champs booléens

Les champs booléens à 2 ou 3 états utilisent les boutons radio pour proposer des options à l'utilisateur vers une clé OSM définie. 2states pour oui/inconnu et 3states pour oui/non/inconnu.

  { "type": "2states", "name": "Libellé", "tag": "tag_key"},
  { "type": "3states", "name": "Libellé", "tag": "tag_key"}

Opérateurs et enseignes

Pour faciliter la sélection d'une enseigne ou d'un réseau de commerces/équipements, le champ de type nsi (pour Name Suggestion Index, un recensement collaboratif des marques et enseignes) peut être utilisé. Celui-ci dispose d'options spécifiques :

path : chemin vers la liste à utiliser (elle apparaît en titre du site web, par exemple brands/shop/coffee)
locationSet : un code pays sur deux lettres, en minuscules, pour ne lister que les enseignes du pays concerné (optionel)

Exemple d'utilisation :

{ "type": "nsi", "name": "Marque", "path": "brands/shop/bakery", "locationSet": "fr" }

Décomptes et statistiques

Les statistiques projet sont établies par le script ./db/09_project_update_tmp.sh. Le script complète la table SQL pdm_feature_counts avec les jours manquant entre le timestamp OSH et le jour courant.

Il est possible de forcer le recomptage de l'intégralité d'un projet en supprimant le fichier de timestamp OSH et en relançant le script

rm ${WORK_DIR}/osh_timestamp
./db/09_project_update_tmp.sh

Points et contributions

Certaines contribution peuvent donner lieu à l'attribution de points aux contributeurs responsables. La configuration des projets établit le lien entre des classes de contribution et les points associés. Il faut donc qualifier certains changement avec les bonnes classes. La plateforme attribue les classes communes suivantes :

add: Les changements concernant des objets version=1
edit : Les changements concernant des objets version>1

Il est possible d'attribuer des classes propres à chaque projet en créant un fichier contribs.sql à côté de info.json. Ce script contient des requêtes UPDATE modifiant les entrées nécessaires de la table pdm_changes. Chaque changement ne peut avoir qu'une classe et ne correspondre qu'à une valeur de point unique.

Les montant de points attribués sont configurés dans info.json :

{
    "statistics": {
		"points": { "add": 3, "project1": 1 }
    }
}

Installation

Choisissez ensuite entre une instance Docker ou locale pour poursuivre. Confère à la section Déploiement ci-dessous pour obtenir un ProjetDuMois exploitable.

Construction Docker

Il est possible de construire un serveur node.js unique pourvu des fonctionnalités nécessaires à toute l'exploitation. Il inclus osmium 1.10.0 avec Debian Buster. L'image Docker n'inclue cependant pas de serveur postgresql et vous pourrez utiliser l'image de CampToCamp.

docker build [--build-arg IMPOSM3_VERSION=0.11.0] -t pdm/server:latest .

Avec :

IMPOSM3_VERSION : Version d'imposm3 à intégrer à l'image Docker

Installation locale

npm install

Déploiement

Base de données

La base de données utilise PostgreSQL. Pour créer la base, lancez la commande :

psql -c "CREATE DATABASE pdm"

Docker

Le service s'installe avec les deux commandes suivantes :

docker run --rm [--network=your-network] -e DB_URL=postgres://user:password@host:5432/database pdm/server:latest install
docker run --rm [--network=your-network] -v host_work_dir:container_work_dir -e DB_URL=postgres://user:password@host:5432/database pdm/server:latest init

Ensuite, lancez le serveur avec la commande :

docker run -d --rm [--network=your-network] -p 3000:3000 --name=pdm -v host_work_dir:container_work_dir -e DB_URL=postgres://user:password@host:5432/database pdm/server:latest run

N'oubliez pas d'ajouter les lignes suivantes dans vos crontab pour mettre à jour les projets périodiquement, idéalement quotidiennement.

docker run --rm [--network=your-network] -v host_work_dir:container_work_dir -e DB_URL=postgres://user:password@host:5432/database pdm/server:latest update_project
docker run --rm [--network=your-network] -v host_work_dir:container_work_dir -e DB_URL=postgres://user:password@host:5432/database pdm/server:latest update_features

Locale

La base de données s'appuie sur PostgreSQL. Pour installer la base :

psql -d pdm -f db/00_init.sql

Le script suivant est à lancer quotidiennement pour récupérer les statistiques de contribution (notes, objets ajoutés, badges obtenus) :

npm run project:update
./db/09_project_update_tmp.sh

Le script suivant est à lancer à la première initialisation de la base de données pour créer la liste des objets venant d'OpenStreetMap :

npm run features:update
./db/21_features_update_tmp.sh init

Le script suivant est à lancer chaque heure pour mettre à jour les objets venant d'OpenStreetMap à afficher sur la carte :

npm run features:update
./db/21_features_update_tmp.sh

Site web

Le code de l'interface web se trouve dans le dossier website. Il s'agit d'un serveur ExpressJS, combiné à des modèles Pug.

Les modèles Pug sont dans le sous-dossier templates. Celui-ci est organisé selon la logique suivante :

Dans templates, le modèle général layout.pug et son fichier CSS
Dans common, les éléments génériques à toutes les pages (<head>, en-tête, pied de page)
Dans components, les composants principaux qui peuplent les pages (carte, bloc statistiques...)
Dans pages, chacune des pages du site (accueil, carte, page projet...)

Le site est visible à l'adresse localhost:3000.

Docker

L'image Docker inclue le nécessaire pour servir le site web et executer les tâches de mise à jour automatiques. Vous pouvez la lancer avec:

docker run -p 3000:3000 [--network=your-network] -e DB_URL=postgres://user:password@host:5432/database pdm/server:latest

Docker compose

Un fichier docker-compose est fourni ici pour faciliter l'execution de la plateforme. Cela ne vous dispensera pas de créer la base de données, y ajouter les bons rôles et configurer pdm de manière appropriée selon la méthode expliquée ci-dessus. Docker-compose permet seulement de faciliter l'execution d'une instance déjà fonctionnelle si et seulement si elle a été configurée correctement préalablement.

En fonction de la configuration de votre serveur Postgresql, vous devrez certainement adapter la valeur de la variable DB_URL dans le fichier compose pour permettre au serveur pdm d'accéder à la base de données correctement.

N'essayez pas de débuter la configuration d'une instance avec docker-compose, essayez plutôt d'obtenir une configuration fonctionnelle de chaque composant et de vous assurer que tout fonctionne séparément d'abord. Une fois que vous avez constaté que tout fonctionnait, lancez-vous avec docker-compose pour faciliter les executions futures.

Pour démarrer :

docker-compose up

Pour arrêter :

docker-compose down

Locale

L'execution locale nécessite un serveur node conforme à la compatilité ci-dessus et des tâches planifiées pour tenir la base de données à jour.

Pour lancer le site web :

export DB_URL="postgres://user:password@host:5432/database" # Database URL
export PORT=3000 # Nodejs port (defaults to 3000)
npm run start

Files

DEVELOP.fr.md

Latest commit

History

DEVELOP.fr.md

File metadata and controls

Contribuer au développement de ProjetDuMois.fr

Dépendances

Compilation osmium

Débuter

Configuration générale

Connexion à Postgresql

Configuration des projets

Temporalité des projets

Se passer d'imposm3

Sources de tuiles

Osmose

Notes OSM

Objets OpenStreetMap

Objets OpenStreetMap pour comparaison

OpenStreetMap extra objects

Fonds raster

Sources stats

Éditeur intégré de Projet du Mois

Attributs statiques ou externes

Champs classiques

Zone de texte

Listes de valeurs

Champs booléens

Opérateurs et enseignes

Décomptes et statistiques

Points et contributions

Installation

Construction Docker

Installation locale

Déploiement

Base de données

Docker

Locale

Site web

Docker

Docker compose

Locale