Aides-territoires

Dépôt du projet Aides-territoires.beta.gouv.fr.

Identifiez en quelques clics toutes les aides disponibles sur votre territoire pour vos projets d'aménagement durable.

Ce document s'adresse aux intervenant·es techniques sur le projet Aides-territoires. Pour plus d'infos en tant qu'utilisateur·ice, se reporter directement au site.

Intégration de l'équipe « onboarding »

Les développeur·euses qui intègrent le projet et doivent monter un environnement de développement local pourront consulter la documentation spécifique.

Démarrage

git clone https://github.com/MTES-MCT/aides-territoires
cd aides-territoires

Tests

Pour faire tourner les tests:

cd src && make test

À noter : certains tests utilisent Selenium qui dépend de geckodriver.

Pour les faire tourner, il conviendra donc d'en télécharger la dernière version pour l'intégrer dans son $PATH.

Définition du fini

Avant chaque mise en production, les intervenant·es sont prié·es de passer cette liste en revue.

Gestion des dépendances avec Pipenv

Le projet utilise Pipenv pour gérer les dépendances de paquets Python et produire des builds déterministes.

Pour installer les dépendances du projet :

pipenv install --dev

Pour installer un nouveau paquet et l'ajouter aux dépendances :

pipenv install <paquet>

Pour un paquet ne servant que pour le développement, e.g debug-toolbar :

pipenv install --dev <paquet>

Configuration locale, production

Le projet utilise django-environ pour gérer les settings des différents environnements ne pouvant être embarquées dans le dépôt git.

Typiquement :

configuration locale spécifique à chaque intervenant·e sur le projet, e.g paramètres de connexion à la base de données ;
configuration de production.

Pour surcharger la configuration locale de développement, il est possible de créer un fichier .env.local à la racine du projet Django. Cf. le fichier .env.example pour l'exemple. Ce fichier est facultatif car des paramètres par défaut sont définis.

En revanche, pour un déploiement en production, la définition d'un fichier .env.production est obligatoire.

CSS, Sass et compression

Maintenir le code HTML propre

Le projet utilise Bootstrap pour faciliter le développement et proposer un rendu homogène. Toutefois, c'est la version Sass du framework css qui est utiliséee, afin d'éviter de pourrir le code HTML de classes non-sémantiques.

Les intervenant·es sur le code sont donc prié·es de ne pas utiliser de classes spécifiques à Bootstrap dans le HTML, mais d'utiliser des classes et ids sémantiques.

Incorrect :

<nav class="navbar navbar-dark bg-dark">
    <div class="container">
        <a class="navbar-brand" href="…">Aides-Territoires</a>
        <ul class="navbar-nav mr-auto">
            <li class="nav-item"><a class="nav-link" href="…">Lien</a></li>
        </ul>
        <span class="text-right navbar-text">Beta</span>
    </div>
</nav>

Correct :

<nav id="main-navbar">
    <div class="container">
        <a class="homelink" href="…">Aides-Territoires</a>
        <ul class="homenav">
            <li><a href="…">Lien</a></li>
        </ul>
        <span>Beta</span>
    </div>
</nav>

nav#main-navbar {
    @extend .navbar;
    @extend .navbar-dark;
    @extend .bg-dark;

    .homelink {
        @extend .navbar-brand;
    }

    ul.homenav {
        @extend .navbar-nav;
        @extend .mr-auto;

        li {
            @extend .nav-item;

            a {
                @extend .nav-link;
            }
        }
    }

    span {
        @extend .text-right;
        @extend .navbar-text;
    }
}

Utilisation de django-compressor

Le projet utilise django-compressor, une application qui permet de gérer la pipeline de compression des fichiers statiques.

Django-compressor propose plusieurs modes de déploiement :

la compilation / compression se fait manuellement une fois pour toute ;
la compilation / compression se fait automatiquement à chaque requête.

Le premier mode de fonctionnement est adapté à un déploiement en production. Le second dans un environnement de développement.

Il faut noter que le second mode peut significativement dégrader les performances et ralentir le travail. Pour améliorer les performances, deux possibilités :

Installer la version native de Sass et pas la version en pure js ;
Désactiver en local la compression par requête dans le fichier .env.local.

COMPRESS_OFFLINE=False

Il faudra alors manuellement lancer la compression en cas de besoin.

python manage.py compress

Déploiement

Le déploiement se fait avec Ansible et ne nécessite qu'une commande.

Un script deploy.py, à la racine du dépôt git, est fourni pour faciliter les opérations.

Pour déployer le code et reconstruire le projet en recette :

python deploy.py build -e stage

Pour déployer en production :

python deploy.py build -e prod

Pour faire tourner l'intégralité du script de livraison (y compris mises à jour de paquets, installations de certificats, configuration de la stack, etc.) :

python deploy.py full -e stage prod

Plus de détails dans le répertoire spécifique.

Mise en production

Le site est actuellement hébergé sur un VPS OVH avec l'option « snapshots » (copie instantanée du vps). Si le déploiement du code ne nécessite qu'une commande, la mise en production effective nécessite de dérouler les étapes suivantes :

alerter l'équipe et vérifier qu'aucune démo ou présentation important n'a actuellement lieu ;
mettre à jour la branche production dans git ;
vérifier que le build passe à 100% ;
se connecter à l'interface OVH ;
supprimer le snapshot existant ;
générer la création d'un nouveau snapshot ;
lancer le déploiement (cf. commandes ci-dessus) ;
annoncer la bonne nouvelle sur Slack ;

sorardev / aides-territoires Goto Github PK