Installer le projet en local

Cette page met en place un environnement de développement sur votre machine. Les étapes se suivent dans l’ordre : installer les outils, cloner le dépôt, configurer, préparer la base de données, puis lancer le site.

Deux approches sont possibles :

  • En natif (méthode utilisée par l’équipe de Sites Conformes) — les étapes ci-dessous ;

  • Avec Docker — une alternative auto-suffisante décrite en fin de page.

Note

Les commandes système sont données pour Ubuntu/Debian ; adaptez-les à votre système (macOS avec Homebrew, etc.).

Les outils du projet

Le projet s’appuie sur trois outils que vous rencontrerez partout :

  • uv — gestionnaire de paquets et d’environnements Python (un remplaçant rapide de pip + venv). Il installe les dépendances aux versions exactes verrouillées dans uv.lock, outils de développement compris.

  • just — lanceur de commandes. Le fichier justfile regroupe des recettes qui enchaînent des commandes Django/uv. Tapez just pour afficher la liste complète.

  • pre-commit — vérifie et formate automatiquement votre code (ruff, black) à chaque git commit. Les hooks sont installés par just init-dev ; sinon, lancez pre-commit install une fois le projet installé.

Astuce

N’oubliez pas d’installer les pre-commit hooks. Sans eux, rien ne formate votre code localement, et le contrôle qualité de la CI échouera : l’intégration continue rejoue pre-commit et just quality (ruff + black) sur l’ensemble des fichiers, et bloque la pull request au moindre écart de formatage.

Indication

Si vous ne voulez pas installer ces outils

  • Sans just : chaque recette n’est qu’un raccourci. Vous pouvez lancer directement les commandes sous-jacentes — les équivalents sont indiqués aux étapes concernées.

  • Sans uv : possible avec pip + venv, mais vous perdez le verrouillage exact des versions. uv reste fortement recommandé en développement. Si vous utilisez uv, pensez à mettre USE_UV=1 dans votre .env (voir plus bas) pour que les recettes just préfixent les commandes par uv run.

Prérequis

Installer :

Sous Ubuntu :

sudo apt install -y git python3 just gettext
# uv (autres méthodes sur https://docs.astral.sh/uv/getting-started/installation/) :
curl -LsSf https://astral.sh/uv/install.sh | sh

Cloner le dépôt

git clone https://github.com/numerique-gouv/sites-conformes.git

# ou en ssh
git clone git@github.com:numerique-gouv/sites-conformes.git

Puis entrez dans le dossier du dépôt :

cd sites-conformes

Configurer l’environnement (.env)

Les réglages locaux se placent dans un fichier .env à la racine du projet. Une recette crée ce fichier à partir du modèle et y génère une SECRET_KEY (elle n’écrase jamais un .env existant) :

just setup-env

Indication

Sans just : faites-le à la main :

cp .env.example .env
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

puis reportez la valeur obtenue dans SECRET_KEY.

Puis renseignez dans .env au moins :

  • DEBUG=True ;

  • HOST_PROTO=http ;

  • USE_UV=1 si vous utilisez uv (pour que les recettes just passent par uv run).

La liste complète des réglages est décrite dans Référence des variables d’environnement.

Préparer la base de données (PostgreSQL)

Avoir un PostgreSQL qui tourne en local (procédure d’installation sur Ubuntu ou sur Mac).

Créez l’utilisateur et la base définis dans votre .env (variables DATABASE_USER, DATABASE_PASSWORD, DATABASE_NAME) :

just setup-db

Indication

Sans just : créez-les à la main (adaptez aux valeurs de votre .env) :

# utilisateur avec les droits nécessaires aux scripts d’administration
psql -U postgres -c "CREATE USER sitesconformes WITH CREATEDB LOGIN PASSWORD 'votre_mot_de_passe';"
# base de données (vide pour l’instant)
psql -U postgres -c "CREATE DATABASE sitesconformes OWNER sitesconformes;"

puis renseignez les paramètres de connexion correspondants dans votre .env.

Installer et initialiser le projet

Une seule commande installe les dépendances (dont celles de développement), lance les migrations, collecte les fichiers statiques, crée les pages de démarrage et installe les pre-commit hooks :

just init-dev

Indication

Sans just : lancez les étapes manuellement (préfixez par uv run si vous utilisez uv, ou activez d’abord votre venv) :

uv sync
python manage.py migrate
python manage.py collectstatic --noinput
python manage.py create_starter_pages
python manage.py import_page_templates
python manage.py import_illustration_images
python manage.py update_index
pre-commit install

Créer un compte administrateur

just createsuperuser

La commande vous demande interactivement une adresse e-mail, un nom d’utilisateur et un mot de passe.

Indication

Sans just :

python manage.py createsuperuser

Lancer le serveur

just runserver

Le site est alors accessible sur http://localhost:8000, et l’administration sur http://localhost:8000/cms-admin/.

Indication

Sans just :

python manage.py runserver

Voir aussi

Pour lister les commandes de gestion Django disponibles :

uv run python manage.py

Avec Docker

Alternative auto-suffisante : le projet fournit un docker-compose.yml. Après avoir copié le .env (voir ci-dessus) et ajouté USE_DOCKER=1, lancez les conteneurs :

docker compose up

Avec USE_DOCKER=1, les recettes just s’exécutent à l’intérieur du conteneur web : vous pouvez donc initialiser le site avec just init-dev puis créer un compte avec just createsuperuser, comme en natif.

Prudence

Ce setup Docker de développement est encore peu éprouvé par l’équipe (qui travaille en natif) : quelques ajustements peuvent être nécessaires. Vos retours et pull requests pour l’améliorer sont les bienvenus.

Options avancées

Courriels en local

Par défaut, les courriels tentent de partir réellement. En développement, vous pouvez les afficher dans le terminal plutôt que de les envoyer, en réglant dans votre .env :

EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

Stockage S3 local avec MinIO

MinIO simule un stockage objet compatible S3 en local, utile pour tester la configuration de production sans vrai bucket S3.

Lancez MinIO :

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -v ~/minio-data:/data \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD=password123 \
  quay.io/minio/minio server /data --console-address ":9001"

Accédez à la console sur http://localhost:9001 (identifiants admin / password123) et créez un bucket (par exemple sc-local). Pour éviter les URLs signées (plus simple en local), rendez-le public : Buckets → sc-local → Anonymous → Add Access Rule → Prefix /, Access readonly.

Ajoutez ensuite dans votre .env :

S3_HOST=host.docker.internal:9000
S3_PUBLIC_HOST=localhost:9000
S3_PROTOCOL=http
S3_KEY_ID=admin
S3_KEY_SECRET=password123
S3_BUCKET_NAME=sc-local
S3_BUCKET_REGION=
S3_LOCATION=medias/

Note

Note : c’est la variable S3_HOST qui active le stockage S3. Sans elle, les médias sont stockés sur le système de fichiers local, quelle que soit la configuration MinIO.

Gestion de la base de données et des médias

La sauvegarde, la récupération des données de production et la restauration sont décrites dans Sauvegarde locale de la base de données et des médias.