Skip to content

Commit 31b82df

Browse files
mborneslafayIGN
mborne
authored and
slafayIGN
committed
docs: split developer-guide, improve docker docs and simplify architecture schema (refs #52)
1 parent d7941ef commit 31b82df

7 files changed

Lines changed: 196 additions & 135 deletions

File tree

‎docs/architecture.jpg‎

-127 KB
Binary file not shown.

‎docs/developer-guide.md‎

Lines changed: 9 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,22 @@
11
# Documentation développeur
22

3+
## Architecture
4+
5+
![Schéma d'architecture logique](img/architecture-logique.drawio.png)
6+
37
## Liens utiles
48

59
* Dépôt GitHub : [https://github.com/IGNF/validator-api](https://github.com/IGNF/validator-api)
610
* Intégration continue avec [GitHub actions](https://github.com/IGNF/validator-api/actions) configurée via le dossier [.github/workflows](https://github.com/IGNF/validator-api/tree/master/.github/workflows)
711

8-
### Prérequis
9-
10-
- Une distribution Linux (de préférence basée sur Debian) pour la machine hôte
11-
- Git
12-
- PHP 7.4 ou 8.1 avec l'extension pgsql
13-
- Yarn
14-
- Serveur web
15-
- Zip/unzip
16-
- Curl
17-
- Java SE >= 11
18-
- ogr2ogr >= 2.3.0
19-
20-
### Installation classique en local
21-
22-
Cloner le dépôt et installez les dépendances PHP :
23-
24-
```bash
25-
git clone https://github.com/IGNF/validator-api.git
26-
cd validator-api
27-
composer install
28-
```
29-
30-
Dupliquez le fichier `.env` sous le nom `.env.local`.
31-
Utilisez les commentaires de `.env.local` pour compléter les paramètres de votre application locale.
32-
33-
Créez la base de données et initialisez sa structure :
34-
35-
```bash
36-
php bin/console doctrine:database:create
37-
php bin/console doctrine:schema:update --force
38-
```
39-
40-
Téléchargez le fichier `bin/validator-cli.jar` :
41-
42-
```bash
43-
# bash download-validator.sh [<MAJOR>.<MINOR>.<PATCH>]
44-
bash download-validator.sh
45-
```
46-
47-
Lancez l'application :
48-
49-
```bash
50-
symfony server:start
51-
```
52-
53-
L'application est consultable à l'adresse http://localhost:8000
54-
55-
56-
En cas de modification des dépendances JS (package.json):
57-
58-
```bash
59-
# installer les dépendances de dev
60-
yarn install
61-
# construire le front à l'aide de webpack
62-
yarn run build
63-
# commiter les modifications
64-
```
65-
66-
### Installation avec docker
67-
68-
```bash
69-
git clone https://github.com/IGNF/validator-api.git
70-
cd validator-api
71-
# démarrage de la stack de développement
72-
docker-compose up -d
73-
# ouvrir http://localhost:8000 avec un navigateur
74-
```
75-
76-
### Architecture
77-
78-
![Architecture](architecture.jpg)
79-
80-
81-
## Tests
82-
83-
### Données de tests
12+
## Données des tests
8413

8514
* Les jeux tests sont dans le dossier `${projectDir}/tests/data`
8615
* Les modèles de données tests utilisés sont des modèles externes (ex : https://www.geoportail-urbanisme.gouv.fr/standard/cnig_SUP_PM3_2016.json)
8716

88-
### Exécution des tests en local
89-
90-
* 1) Installez les dépendances PHP
91-
92-
```bash
93-
composer install
94-
```
95-
96-
* 2) Configurez la base de données de test
97-
98-
Dans `.env.test`, ajoutez la ligne suivante :
99-
100-
```
101-
DATABASE_URL=postgresql://${PGUSER}:${PGPASSWORD}@localhost:5432/validator_api_test?serverVersion=13&charset=utf8
102-
```
103-
104-
> [Comment configurer la variable DATABASE_URL (documentation Symfony)](https://symfony.com/doc/4.4/doctrine.html#configuring-the-database)
105-
106-
Puis :
107-
108-
```bash
109-
# Créer la base de données
110-
php bin/console --env=test doctrine:database:create --if-not-exists
111-
# Mettre à jour le schéma de la base de donnnées
112-
php bin/console --env=test doctrine:schema:update --force
113-
```
114-
115-
* 3) Téléchargez l'exécutable java validator-cli.jar
116-
117-
Si `validator-cli.jar` est déjà installé, vous pouvez configurer son emplacement à l'aide de la ligne suivante dans `.env.test` :
118-
119-
```
120-
VALIDATOR_PATH=/opt/ign-validation/validator-cli.jar
121-
```
122-
123-
Sinon, vous pouvez lancer `bash download-validator.sh <VALIDATOR_VERSION>` pour le télécharger dans `${projectDir}/bin/validator-cli.jar` (chemin par défaut)
124-
125-
* 4) Exécutez les tests
126-
127-
```bash
128-
XDEBUG_MODE=coverage APP_ENV=test php vendor/bin/simple-phpunit
129-
```
130-
131-
* 5) Consulter les rapports
132-
133-
Voir `${projectDir}/var/data/output` pour les résultats des tests.
134-
135-
136-
### Analyse de code avec Sonarqube
137-
138-
* Installer [sonar-scanner](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/)
139-
* Configurer les variables d'environnement `SONAR_HOST_URL` et `SONAR_TOKEN`
140-
* Exécuter `sonar-scanner` :
17+
## Procédure d'installation
14118

142-
```bash
143-
cd validator-api
144-
# lancer l'analyse de code
145-
sonar-scanner
146-
```
19+
* [Documentation développeur pour développement PHP classique](developer-guide/php-classic.md)
20+
* [Documentation développeur pour développement avec docker](developer-guide/docker.md)
21+
* [Documentation développeur pour le développement du front (JavaScript)](developer-guide/front.md)
14722

148-
Remarque : Le fichier de configuration du projet Sonarqube est à la racine : [sonar-project.properties](../sonar-project.properties)

‎docs/developer-guide/docker.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Documentation développeur pour développement avec docker
2+
3+
## Prérequis
4+
5+
* docker
6+
* docker compose
7+
8+
## Principes
9+
10+
* L'image est définie par le fichier [.docker/Dockerfile](../../.docker/Dockerfile) avec deux "targets" :
11+
* `prod` construite avec GitHub actions et stockée sur GitHub container registry
12+
* `dev` (incluant xdebug) construite et utilisée par [docker-compose.yml](../../docker-compose.yml)
13+
* Un script utilitaire [.docker/application.sh](../../.docker/application.sh) est intégré à l'image pour simplifier l'initialisation de la base et l'exécution des tests en environnement de développement.
14+
15+
## Paramètrage
16+
17+
Le paramétrage de l'application est réalisé via des variables d'environnements. Voir [.env](../../.env) servant de modèle.
18+
19+
Le script [.docker/application.sh](../../.docker/application.sh) comporte des options spécifiques au démarrage de l'API :
20+
21+
* `DB_CREATE` à définir à 0 ou 1 pour créer automatiquement la base de données
22+
* `DB_UPGRADE` à définir à 0 ou 1 pour mettre à jour automatiquement la structure
23+
24+
## Construction et démarrage de l'application
25+
26+
```bash
27+
git clone https://github.com/IGNF/validator-api.git
28+
cd validator-api
29+
# Construction de l'image docker
30+
docker compose build
31+
# Démarrage de la stack de développement
32+
docker compose up -d
33+
# Ouvrir http://localhost:8000 avec un navigateur
34+
```
35+
36+
## Exécution des tests
37+
38+
```bash
39+
# Exécution des tests dans l'image docker
40+
docker compose exec api .docker/application.sh test
41+
```
42+
43+
Pour tester via l'interface :
44+
45+
* Ouvrir http://localhost:8000
46+
* Choisir le fichier [tests/data/cnig-pcrs-lyon-01-3946.zip](../../tests/data/cnig-pcrs-lyon-01-3946.zip)
47+
* Choisir la projection EPSG:3946
48+
* Valider et attendre le résultat
49+
50+
## Quelques commandes utiles pour le debug
51+
52+
* Visualiser les logs du backend : `docker compose logs -f backend`
53+
* Ouvrir un terminal dans le conteneur : `docker compose exec api /bin/bash`
54+
* Lister les fichiers : `docker compose exec api find var/data/validations`
55+
* Suivre un traitement particulier : `docker compose exec api tail -f var/data/validations/${VALIDATION_ID}/validator-debug.log`
56+
57+
58+

‎docs/developer-guide/front.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
2+
# Documentation développeur pour le développement du front (JavaScript)
3+
4+
## Principe
5+
6+
* Les dépendances JS sont commitées dans le dossier `public/vendor`
7+
* En cas de modification des dépendances JS (package.json), il convient de reconstruire et commit
8+
9+
## Procédure de mise à jour
10+
11+
```bash
12+
# installer les dépendances de dev
13+
yarn install
14+
# construire le front à l'aide de webpack
15+
yarn run build
16+
# commiter les modifications
17+
```

‎docs/developer-guide/php-classic.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
2+
# Documentation développeur pour développement PHP classique
3+
4+
## Prérequis
5+
6+
- Une distribution Linux (de préférence basée sur Debian) pour la machine hôte
7+
- Git
8+
- PHP 7.4, 8.1 ou 8.2 avec l'extension pgsql
9+
- Yarn
10+
- Serveur web
11+
- Zip/unzip
12+
- Curl
13+
- Java SE >= 11
14+
- ogr2ogr >= 2.3.0
15+
16+
## Procédure d'installation du projet PHP
17+
18+
* Cloner le dépôt et installez les dépendances PHP :
19+
20+
```bash
21+
git clone https://github.com/IGNF/validator-api.git
22+
cd validator-api
23+
composer install
24+
```
25+
26+
* Dupliquer et adapter le fichier `.env` sous le nom `.env.local`.
27+
28+
Utilisez les commentaires de `.env.local` pour compléter les paramètres de votre application locale.
29+
30+
* Créer la base de données et initialiser sa structure :
31+
32+
```bash
33+
php bin/console doctrine:database:create
34+
php bin/console doctrine:schema:update --force
35+
```
36+
37+
* Télécharger le fichier `bin/validator-cli.jar` :
38+
39+
```bash
40+
# bash download-validator.sh [<MAJOR>.<MINOR>.<PATCH>]
41+
bash download-validator.sh
42+
```
43+
44+
* Lancer l'application :
45+
46+
```bash
47+
symfony server:start
48+
```
49+
50+
L'application est consultable à l'adresse http://localhost:8000
51+
52+
53+
## Exécution des tests
54+
55+
* 1) Configurer la base de données de test
56+
57+
Dans `.env.test`, ajoutez la ligne suivante :
58+
59+
```
60+
DATABASE_URL=postgresql://${PGUSER}:${PGPASSWORD}@localhost:5432/validator_api_test?serverVersion=13&charset=utf8
61+
```
62+
63+
> [Comment configurer la variable DATABASE_URL (documentation Symfony)](https://symfony.com/doc/4.4/doctrine.html#configuring-the-database)
64+
65+
* 2) Initialiser la base de données de test
66+
67+
```bash
68+
# Créer la base de données
69+
php bin/console --env=test doctrine:database:create --if-not-exists
70+
# Mettre à jour le schéma de la base de donnnées
71+
php bin/console --env=test doctrine:schema:update --force
72+
```
73+
74+
* 3) Téléchargez l'exécutable java validator-cli.jar
75+
76+
Si `validator-cli.jar` est déjà installé, vous pouvez configurer son emplacement à l'aide de la ligne suivante dans `.env.test` :
77+
78+
```
79+
VALIDATOR_PATH=/opt/ign-validation/validator-cli.jar
80+
```
81+
82+
Sinon, vous pouvez lancer `bash download-validator.sh <VALIDATOR_VERSION>` pour le télécharger dans `${projectDir}/bin/validator-cli.jar` (chemin par défaut)
83+
84+
* 4) Exécutez les tests
85+
86+
```bash
87+
XDEBUG_MODE=coverage APP_ENV=test php vendor/bin/simple-phpunit
88+
```
89+
90+
* 5) Consulter les rapports
91+
92+
Voir `${projectDir}/var/data/output` pour les résultats des tests.

‎docs/developer-guide/sonarqube.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
2+
# Documentation développeur - analyse de code avec Sonarqube
3+
4+
## Principe
5+
6+
Un fichier de configuration du projet Sonarqube à la racine du projet : [sonar-project.properties](../../sonar-project.properties). Il est exploité pour alimenter une instance sonarqube IGN non exposée sur internet.
7+
8+
## Procédure
9+
10+
* Installer [sonar-scanner](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/)
11+
* Configurer les variables d'environnement `SONAR_HOST_URL` et `SONAR_TOKEN`
12+
* Exécuter `sonar-scanner` :
13+
14+
```bash
15+
cd validator-api
16+
# lancer l'analyse de code
17+
sonar-scanner
18+
```
19+
20+

‎docs/img/architecture-logique.drawio.png‎

42.9 KB
Loading

0 commit comments

Comments
 (0)