SCI Rental Manager

Application de gestion locative pour SCI, auto-hébergeable via Docker, Traefik et Forgejo.

---

Stack technique

Frontend Web

Vue 3
TypeScript
PrimeVue
Vite

Mobile Frontend

Vue 3
TypeScript
Vite
Capacitor
Pinia
Axios

Backend

FastAPI
SQLAlchemy
Pydantic

Base de données

PostgreSQL

Infrastructure

Docker
Docker Compose
Traefik
Forgejo
Forgejo Runner

---

Fonctionnalités

Dashboard

• Nombre de réservations
• Revenus encaissés
• Revenus prévisionnels
• Locations en cours
• Arrivées prochaines
• Calendrier des réservations

Biens

• CRUD complet

Locataires

• CRUD complet

Réservations

• CRUD complet
• Calendrier mensuel
• Affichage par bien
• Couleurs par propriété

---

Développement local

Backend

Installation des dépendances

cd backend

uv sync

PostgreSQL via Docker Compose

  Arrêter et supprimer les volumes :

⚠️ Cette opération supprime toutes les données.

docker compose down -v

  Redémarrer PostgreSQL :  

docker compose up -d 

  Vérifier que le conteneur est bien démarré :  

docker ps

  Recréer les tables :  

cd backend

uv run python -m database.session

Lancement

uv run uvicorn main:app --reload

Swagger :

http://localhost:8000/docs

---

Tests

Tous les tests :

uv run pytest

Mode verbeux :

uv run pytest -v

Un fichier :

uv run pytest tests/test_bookings.py -v

---

Recréer l'environnement Python

rm -rf .venv

uv sync

---

Frontend

Installation

cd frontend

npm install

Lancement

npm run dev

Application :

http://localhost:5173

Build

npm run build

---

Mobile Frontend

Installation

cd mobile

npm install

Développement (Navigateur)

cd mobile

npm run dev

Application accessible sur http://localhost:5174 avec proxy vers l'API sur http://localhost:8000.

Configuration

Copier .env.example vers .env.local et ajuster l'URL de l'API :

cp .env.example .env.local
# Éditer .env.local
VITE_API_URL=http://localhost:8000

Build Production (Web)

cd mobile

npm run build

Les assets sont générés dans mobile/dist/.

Build Android (Local - x86_64)

cd mobile

npm run build
npx cap sync android
cd android
./gradlew assembleDebug

L'APK sera dans mobile/android/app/build/outputs/apk/debug/app-debug.apk.

Build Android (Docker - ARM/Raspberry Pi / CI)

# Depuis la racine du projet
docker build -t sci-rental-mobile-android -f Dockerfile.android .
docker run --rm -v $(pwd)/mobile:/workspace sci-rental-mobile-android

Ou pour extraire l'APK :

docker build -t sci-rental-mobile-android -f Dockerfile.android .
docker create --name extractor sci-rental-mobile-android:latest
docker cp extractor:/app-debug.apk ./mobile/app-debug.apk
docker rm extractor

Build Android AAB (Pour Play Store)

docker build --build-arg BUILD_AAB=true -t sci-rental-mobile-android-aab -f Dockerfile.android .
docker create --name extractor-aab sci-rental-mobile-android-aab:latest
docker cp extractor-aab:/app-debug.aab ./mobile/app-debug.aab
docker rm extractor-aab

Ouvrir dans Android Studio

cd mobile

npm run build
npx cap open android

---

Docker

Backend

Build

cd backend

docker build \
  -t sci-rental-manager-backend:local .

Run

docker run --rm \
  -p 8000:8000 \
  sci-rental-manager-backend:local

Swagger :

http://localhost:8000/docs

---

Frontend

Build

cd frontend

docker build \
  -t sci-rental-manager-frontend:local .

Run

docker run --rm \
  -p 8080:80 \
  sci-rental-manager-frontend:local

Application :

http://localhost:8080

---

Docker Compose

Lancement complet

docker compose \
  --env-file deploy/.env \
  -f deploy/docker-compose.prod.yml \
  up -d

---

Rebuild complet

docker compose \
  --env-file deploy/.env \
  -f deploy/docker-compose.prod.yml \
  up -d --build

---

Arrêt

docker compose \
  --env-file deploy/.env \
  -f deploy/docker-compose.prod.yml \
  down

---

Logs

Tous les services :

docker compose \
  --env-file deploy/.env \
  -f deploy/docker-compose.prod.yml \
  logs -f

Backend :

docker logs -f sci-rental-backend

Frontend :

docker logs -f sci-rental-frontend

PostgreSQL :

docker logs -f sci-rental-db

---

Registry Forgejo

Connexion :

docker login forgejo.humectzx.duckdns.org

Images publiées :

forgejo.humectzx.duckdns.org/hume/sci-rental-manager-backend
forgejo.humectzx.duckdns.org/hume/sci-rental-manager-frontend

---

CI/CD

Créer une release

Commit :

git add .

git commit -m "feat: description"

git push

Créer un tag :

git tag 0.0.1

git push origin 0.0.1

---

Pipeline Forgejo

Déclenchement :

Push d'un tag

Pipeline :

Tests backend
↓
Build frontend
↓
Build image backend
↓
Push image backend
↓
Build image frontend
↓
Push image frontend

---

Pipeline Mobile

Déclenchement :

Push sur mobile/** (branche main ou feature/*)
Pull Request sur main touchant mobile/**
Workflow dispatch manuel

Pipeline Mobile :

build-web (Node.js 20)
  ↓ Type-check + Vite build
  ↓ Artifact: mobile-web-dist
  
build-android (Docker x86_64)
  ↓ Build APK via Dockerfile.android
  ↓ Artifact: mobile-app-debug-apk (30 jours)
  
build-aab (Docker x86_64) - main uniquement
  ↓ Build AAB via Dockerfile.android (BUILD_AAB=true)
  ↓ Artifact: mobile-app-debug-aab (30 jours)

---

Déploiement serveur

Choisir une version

Modifier :

VERSION=0.0.1

---

Télécharger les nouvelles images

docker compose pull

---

Déployer

docker compose up -d

---

Rollback

Revenir à la version précédente :

VERSION=0.0.0

Puis :

docker compose up -d

---

Commandes utiles Docker

Lister les conteneurs :

docker ps

Lister les images :

docker images

Ouvrir un shell dans un conteneur :

docker exec -it sci-rental-backend sh

Supprimer les ressources inutilisées :

docker system prune -f

---

Commandes utiles Git

Status :

git status

Historique :

git log --oneline --graph

Tags :

git tag

Supprimer un tag local :

git tag -d 0.0.1

Supprimer un tag distant :

git push origin :refs/tags/0.0.1

---

Architecture

┌─────────────────┐     ┌─────────────────┐
│  Frontend Web   │     │  Mobile App     │
│   (Vue 3)       │     │  (Vue 3 +       │
│                 │     │   Capacitor)    │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
            ┌─────────────────┐
            │   Backend       │
            │   (FastAPI)     │
            └────────┬────────┘
                     ▼
            ┌─────────────────┐
            │  SQLAlchemy     │
            └────────┬────────┘
                     ▼
            ┌─────────────────┐
            │  PostgreSQL     │
            └────────┬────────┘
                     ▼
            ┌─────────────────┐
            │    Docker       │
            └────────┬────────┘
                     ▼
            ┌─────────────────┐
            │   Traefik       │
            └────────┬────────┘
                     ▼
               Internet

---

Objectif

Application de gestion locative auto-hébergée permettant :

• Gestion des biens
• Gestion des locataires
• Gestion des réservations
• Tableau de bord
• Planning visuel
• Déploiement automatisé via Forgejo
• Publication d'images Docker versionnées
• Application mobile read-only (Android/iOS via Capacitor)
• Dashboard mobile avec stats, réservations en cours, arrivées
• Notifications push (prévu)

Gestion des migrations de base de données avec Alembic

Le projet utilise Alembic pour gérer l'évolution du schéma de la base de données PostgreSQL.

Initialiser une base vierge

cd backend
uv run alembic upgrade head

Cette commande appliquera toutes les migrations en attente, créant les tables nécessaires.

Mettre à jour une base existante

Lorsqu'une nouvelle migration est ajoutée au dépôt (après un `git pull`):

cd backend
uv run alembic upgrade head

Créer une nouvelle migration après modification des modèles

1. Modifier les modèles SQLAlchemy dans `backend/models/`.
2. Générer automatiquement un script de migration :

uv run alembic revision --autogenerate -m "description courte du changement"

3. Vérifier le fichier généré dans `backend/alembic/versions/` pour s'assurer qu'il correspond aux changements attendus.
4. Appliquer la migration en local pour tester :

uv run alembic upgrade head

5. Committer à la fois les modifications de modèles et le nouveau fichier de migration.

Revenir à une version précédente (à utiliser avec précaution)

# Revenir d'une révision
uv run alembic downgrade -1
# Revenir à la base (supprime toutes les tables - perte de données !)
uv run alembic downgrade base

Voir l'historique et l'état actuel

# Voir la révision actuellement appliquée
uv run alembic current
# Voir l'historique complet des migrations
uv run alembic history

Note

: Les tests utilisent une base SQLite en mémoire qui recrée le schéma via `Base.metadata.create_all` ; ils n'appellent pas Alembic. Ainsi, les tests peuvent passer même si votre base de développement n'est pas à jour. Pensez toujours à exécuter `alembic upgrade head` sur votre base de développement après un `git pull` qui inclut de nouvelles migrations.