Deploiement Local - Guide complet du developpeur¶

Ce guide accompagne un developpeur de bout en bout : du poste vierge jusqu'a un environnement local complet, avec des donnees realistes issues de la devtest, puis la marche a suivre pour poursuivre le developpement.

Chaque etape se termine par un bloc Verification : ne pas passer a l'etape suivante tant que la verification n'est pas verte.

flowchart LR
    A[0. Prerequis] --> B[1. Cloner]
    B --> C[2. Configurer .env.local]
    C --> D[3. Demarrer la stack]
    D --> E[4. Verifier l'app]
    E --> F[5. Charger un dump devtest]
    F --> G[6. Developper]
    G --> H[7. Pousser sur dev -> deploiement test auto]

0. Prerequis¶

Outil	Version minimale	Verifier
Docker Desktop	20.10+	`docker --version`
Docker Compose	v2	`docker compose version`
Git	2.x	`git --version`

Sous Windows : installer Docker Desktop (avec WSL2) et Git for Windows. Lancer Docker Desktop et attendre qu'il soit "Running".

Verification

docker --version && docker compose version && git --version
docker run --rm hello-world      # doit afficher "Hello from Docker!"

Si hello-world fonctionne, Docker est operationnel.

1. Cloner le depot¶

git clone https://github.com/Boaz-study-organization/Boaz-study-fullstack-housing.git
cd Boaz-study-fullstack-housing

Verification

ls docker-compose.local.yml .env.local.example    # les deux doivent exister
git branch -a                                       # voir main et origin/dev

2. Configurer `.env.local`¶

1	`cp .env.local.example .env.local`

Ouvrir .env.local et renseigner au minimum :

STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEY / STRIPE_WEBHOOK_SECRET : cles de TEST (sk_test_..., pk_test_..., whsec_...). Les recuperer dans le dashboard Stripe (mode test).
REACT_APP_GOOGLE_MAPS_API_KEY : une cle Google Maps (peut rester vide au debut ; la carte ne s'affichera pas mais le reste fonctionne).
SECRET_KEY : generer une valeur -> openssl rand -hex 32.
Les mots de passe (POSTGRES_PASSWORD, PGADMIN_PASSWORD) : laisser les valeurs locales par defaut.

Jamais de cle Stripe LIVE en local

En local, utiliser EXCLUSIVEMENT des cles Stripe de test (sk_test_ / pk_test_). Une cle live declencherait de vrais paiements.

Ports parametrables

Si un port est deja pris sur votre poste, changez-le dans .env.local : FRONTEND_PORT, BACKEND_PORT, POSTGRES_PORT, PGADMIN_PORT.

Verification

# aucune cle live ne doit apparaitre :
grep -E 'sk_live|pk_live' .env.local && echo "RETIRER LES CLES LIVE" || echo "OK (pas de cle live)"
# le fichier n'est pas suivi par git (il est ignore) :
git check-ignore .env.local     # doit afficher .env.local

3. Demarrer la stack locale¶

docker compose -f docker-compose.local.yml --env-file .env.local up --build

La premiere fois, le build prend quelques minutes (images backend + frontend). Laisser tourner ; les logs s'affichent. Pour lancer en arriere-plan : ajouter -d.

Au demarrage, le backend applique automatiquement les migrations et cree un jeu d'utilisateurs par defaut.

Verification

Dans un autre terminal :

docker compose -f docker-compose.local.yml ps      # 4 services Up (postgres, backend, frontend, pgadmin)
curl -s http://localhost:8001/health               # {"status":"ok"}

Dans les logs de demarrage, chercher : Migrations appliquees avec succes puis Application startup complete.

4. Verifier l'application¶

Service	URL	Attendu
Frontend	http://localhost:3001	L'interface Boaz Housing s'affiche
API (Swagger)	http://localhost:8001/docs	La documentation interactive de l'API
API (sante)	http://localhost:8001/health	`{"status":"ok"}`
pgAdmin	http://localhost:5060	Console pgAdmin (identifiants dans `.env.local`)

Verification

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3001          # 200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/docs     # 200
curl -sL http://localhost:8001/api/logements                            # [] (base vierge) ou une liste

Se connecter a la base avec pgAdmin¶

Ouvrir http://localhost:5060 (se connecter avec PGADMIN_EMAIL / PGADMIN_PASSWORD).
Ajouter un serveur : Host = housing_local_db, Port = 5432, User/Password = POSTGRES_USER / POSTGRES_PASSWORD du .env.local.

5. Charger des donnees realistes (restauration de la base locale)¶

Par defaut la base locale est vierge. Pour developper avec des donnees realistes, on restaure la base locale a partir d'un dump. Deux possibilites :

Option A (la plus simple) : utiliser le dump deja present dans le depot (seed/housing_dev_seed.sql.gz). Rien a telecharger.
Option B : recuperer un dump frais depuis le serveur (donnees a jour).

Dans les deux cas, la restauration se fait avec le meme script scripts/seed-local-db.sh, qui sauvegarde la base locale actuelle avant d'ecraser.

flowchart TD
    subgraph "Option A - dump du depot"
      A1[seed/housing_dev_seed.sql.gz<br/>deja clone avec le repo]
    end
    subgraph "Option B - dump du serveur"
      B1[ops/export_test_dump.sh sur le serveur] --> B2[scp vers le poste]
    end
    A1 --> R[scripts/seed-local-db.sh]
    B2 --> R
    R --> D[(Base locale peuplee)]

Option A - Restaurer avec le dump du depot (recommande)¶

Le depot contient deja un dump pret a l'emploi dans seed/housing_dev_seed.sql.gz. La stack locale doit tourner (etape 3).

Etape A.1 - Verifier que le dump est bien present et integre

ls -lh seed/housing_dev_seed.sql.gz       # le fichier existe et n'est pas vide
gzip -t seed/housing_dev_seed.sql.gz && echo "archive integre"

Etape A.2 - Restaurer

1	`bash scripts/seed-local-db.sh seed/housing_dev_seed.sql.gz`

Le script affiche a la fin le nombre de souscriptions importees, par exemple : [seed-local] Termine. souscriptions=149.

Etape A.3 - Verifier la restauration

# 1) Compter les lignes directement en base (doit etre > 0)
docker compose -f docker-compose.local.yml exec postgres \
  psql -U boaz_user -d boaz_housing_local -tAc "SELECT count(*) FROM souscriptions;"

# 2) Via l'API (attendre ~5s que le backend redemarre)
curl -sL http://localhost:8001/api/logements | head -c 200      # une liste non vide

# 3) Dans le navigateur
#    http://localhost:3001  -> des logements / souscriptions s'affichent

Verification reussie si

la commande SQL renvoie un nombre > 0 (ex. 149) ;
l'API /api/logements renvoie une liste non vide ;
l'interface http://localhost:3001 affiche des donnees.

Mettre a jour le dump du depot

Le dump du depot est un instantane. Pour des donnees plus recentes, utiliser l'Option B, ou regenerer le dump (voir seed/README.md).

Option B - Recuperer un dump frais depuis le serveur¶

Pour des donnees a jour, produire un dump sur le serveur puis le rapatrier.

Etape B.1 - Produire le dump (sur le SERVEUR, lecture seule sur la devtest)

bash /home/ubuntu/Projet_boaz_housing_fullstack/ops/export_test_dump.sh
# -> cree ops/dumps/boaz_housing_test_<date>.sql.gz

Etape B.2 - Rapatrier sur le POSTE local

scp ubuntu@151.80.144.98:/home/ubuntu/Projet_boaz_housing_fullstack/ops/dumps/boaz_housing_test_*.sql.gz .

Alternative : un dump de sauvegarde nocturne (boaz_housing_mvp.sql.gz) depuis S3 HOUSING/NIGHTLY/<date>/ si vous avez les acces.

Etape B.3 - Verifier puis restaurer

gzip -t boaz_housing_test_*.sql.gz && echo "archive integre"
bash scripts/seed-local-db.sh boaz_housing_test_<date>.sql.gz

Etape B.4 - Verifier la restauration : identique a l'etape A.3 ci-dessus.

Donnees reelles et cles Stripe

Les dumps peuvent contenir des donnees clients reelles (la base de test est alimentee par un snapshot de la production). Ne pas les diffuser hors de l'organisation. En local, utiliser EXCLUSIVEMENT des cles Stripe de test.

6. Poursuivre le developpement¶

6.1 Cycle de travail au quotidien¶

flowchart LR
    A[git switch -c ma-feature origin/dev] --> B[Coder<br/>hot-reload actif]
    B --> C[Tester en local]
    C --> D[git commit]
    D --> E[git push origin ma-feature]
    E --> F[Pull Request vers dev]
    F --> G[Merge dev -> deploiement TEST auto]
    G --> H[Valider sur test-housing]
    H --> I[Pull Request dev -> main]
    I --> J[Merge main -> deploiement PROD auto]

6.2 Demarrer une fonctionnalite¶

Toujours partir de dev (la branche d'integration) :

git fetch origin
git switch -c ma-feature origin/dev

6.3 Coder avec rechargement automatique¶

En local, le code est monte dans les conteneurs (backend/ et frontend/src) :

Backend : modifier un fichier Python -> l'API redemarre automatiquement (uvicorn --reload).
Frontend : modifier un fichier React -> la page se recharge automatiquement.

Verification du hot-reload

Modifier un texte dans frontend/src et sauvegarder : la page http://localhost:3001 se met a jour seule. Modifier un endpoint backend : http://localhost:8001/docs reflete le changement apres quelques secondes.

6.4 Base de donnees et migrations¶

Si vous modifiez un modele (SQLAlchemy), creez une migration Alembic :

docker compose -f docker-compose.local.yml exec backend alembic revision --autogenerate -m "description"
docker compose -f docker-compose.local.yml exec backend alembic upgrade head

Migrations reproductibles

Une migration doit fonctionner sur une base vierge (elle sera rejouee en test et en prod). Eviter tout identifiant en dur ; ne jamais appeler connection.commit() au milieu d'une migration. Pour un ALTER TYPE ... ADD VALUE, utiliser op.get_context().autocommit_block().

6.5 Verifier avant de pousser¶

# les tests backend (si presents)
docker compose -f docker-compose.local.yml exec backend pytest -q
# l'app repond toujours
curl -s http://localhost:8001/health

6.6 Pousser et deployer¶

git add -A && git commit -m "message clair"
git push origin ma-feature

Ouvrir une Pull Request vers dev. Apres merge dans dev, le deploiement en TEST est automatique (CI/CD). Verifier sur https://test-housing.boaz-study.tech.

Quand la fonctionnalite est validee en test, une PR dev -> main ; apres merge, le deploiement en PRODUCTION est automatique (avec sauvegarde + rollback).

Regles

Ne jamais committer de fichier .env reel ni de secret (seuls .env.local.example et .env.template sont versionnes).
Ne jamais mettre de mention d'outil d'IA dans les commits, PR ou merges.
Auteur des commits : joel kemkeng <kedikemkeng@gmail.com>.

7. Arret, reprise, depannage¶

Arreter / relancer¶

docker compose -f docker-compose.local.yml down          # arrete (garde les donnees)
docker compose -f docker-compose.local.yml up -d          # relance

Repartir de zero (efface la base locale)¶

docker compose -f docker-compose.local.yml down -v         # -v supprime les volumes locaux
docker compose -f docker-compose.local.yml --env-file .env.local up --build

Problemes frequents¶

Symptome	Cause probable	Solution
`port is already allocated`	Un port local est deja pris	Changer le port dans `.env.local`
Le frontend ne se recharge pas (Windows)	Detection de fichiers	`CHOKIDAR_USEPOLLING=true` est deja active
`password authentication failed`	Mot de passe DB incoherent	Verifier `POSTGRES_PASSWORD` dans `.env.local`, `down -v` puis relancer
La carte ne s'affiche pas	Cle Google Maps absente/invalide	Renseigner `REACT_APP_GOOGLE_MAPS_API_KEY`

Voir les logs¶

docker compose -f docker-compose.local.yml logs -f backend
docker compose -f docker-compose.local.yml logs -f frontend

Deploiement Local - Guide complet du developpeur¶

0. Prerequis¶

1. Cloner le depot¶

2. Configurer .env.local¶

3. Demarrer la stack locale¶

4. Verifier l'application¶

Se connecter a la base avec pgAdmin¶

5. Charger des donnees realistes (restauration de la base locale)¶

Option A - Restaurer avec le dump du depot (recommande)¶

Option B - Recuperer un dump frais depuis le serveur¶

6. Poursuivre le developpement¶

6.1 Cycle de travail au quotidien¶

6.2 Demarrer une fonctionnalite¶

6.3 Coder avec rechargement automatique¶

6.4 Base de donnees et migrations¶

6.5 Verifier avant de pousser¶

6.6 Pousser et deployer¶

7. Arret, reprise, depannage¶

Arreter / relancer¶

Repartir de zero (efface la base locale)¶

Problemes frequents¶

Voir les logs¶

2. Configurer `.env.local`¶