Set up initial frontend with Vite and integrated Docker for full-stack build

2026-04-19 22:24:59 +02:00
commit ac63c4be99
37 changed files with 9796 additions and 0 deletions
@@ -0,0 +1,192 @@
+# Budget Commun
+
+Application web PWA pour gérer un budget partagé en couple (ou en famille).
+Hébergeable sur un NAS ou tout serveur local. Installable sur iPhone/Android depuis Safari/Chrome.
+
+**Fonctionnalités :**
+- Budget commun + budgets personnels par utilisateur
+- Dépenses récurrentes (mensuel, hebdo, annuel, ponctuel, paiement en x fois)
+- Pointage mensuel des dépenses
+- Simulateur de projets d'épargne
+- Gestion des épargnes avec suivi du solde
+- Thème sombre / clair / système
+- Pull-to-refresh sur mobile
+- PWA installable (fonctionne hors-ligne en lecture)
+
+---
+
+## Stack technique
+
+- **Frontend** : React + Vite (SPA, PWA)
+- **Backend** : Node.js / Express
+- **Base de données** : PostgreSQL 16
+- **Authentification** : JWT (30 jours)
+- **Déploiement** : Docker / Docker Compose
+
+---
+
+## Structure du projet
+
+```
+budget-commun/
+├── docker-compose.yml       ← déploiement standard
+├── backend/
+│   ├── Dockerfile           ← build multi-stage (frontend + backend)
+│   ├── server.js            ← API Express + initialisation BDD
+│   └── package.json
+└── frontend/
+    ├── src/
+    │   ├── pages/           ← Dashboard, Dépenses, Pointage, Simulateur, Épargnes…
+    │   ├── contexts/        ← Auth, Budget, Theme
+    │   ├── hooks/
+    │   └── api/
+    ├── public/
+    │   ├── sw.js            ← Service Worker (network-first)
+    │   ├── manifest.json
+    │   └── favicon.svg
+    └── package.json
+```
+
+Le Dockerfile est **multi-stage** : il build le frontend Vite, puis l'embarque dans l'image Node.js qui sert à la fois l'API et les fichiers statiques sur le port **3000**.
+
+---
+
+## Démarrage rapide (Docker Compose)
+
+```bash
+docker compose up -d
+```
+
+L'application est accessible sur `http://localhost:3456`.
+
+**Identifiants par défaut :**
+| Utilisateur | Mot de passe |
+|-------------|--------------|
+| user1       | password1    |
+| user2       | password2    |
+
+> **Sécurité** : changez les mots de passe depuis **Mon compte → Changer le mot de passe** après la première connexion.
+
+---
+
+## Configuration
+
+Les variables d'environnement peuvent être définies dans un fichier `.env` (voir `.gitignore`) :
+
+| Variable       | Défaut                                           | Description                        |
+|----------------|--------------------------------------------------|------------------------------------|
+| `DATABASE_URL` | `postgres://budget:budget@db:5432/budget`        | Connexion PostgreSQL               |
+| `JWT_SECRET`   | `budget-commun-secret-change-me`                 | Secret de signature JWT            |
+| `ADMIN_USER`   | `user1`                                          | Nom d'utilisateur administrateur   |
+
+Pour la production, définissez au minimum `JWT_SECRET` avec une valeur aléatoire longue.
+
+---
+
+## Déploiement sur TrueNAS SCALE (Custom App)
+
+TrueNAS ne supporte pas `docker compose` directement. Utilisez **Custom App** via `midclt` :
+
+### 1. Charger l'image sur le NAS
+
+Depuis votre machine de build :
+```bash
+# Build pour l'architecture amd64 (TrueNAS)
+docker buildx build --platform linux/amd64 -t budget-commun:latest -f backend/Dockerfile .
+
+# Transférer sur le NAS
+docker save budget-commun:latest | ssh admin@<IP-NAS> "sudo docker load"
+```
+
+### 2. Créer l'application
+
+```bash
+ssh admin@<IP-NAS>
+
+sudo midclt call app.create '{
+  "name": "budget-commun",
+  "custom_app": true,
+  "custom_compose_config": {
+    "services": {
+      "db": {
+        "image": "postgres:16-alpine",
+        "restart": "unless-stopped",
+        "environment": {
+          "POSTGRES_DB": "budget",
+          "POSTGRES_USER": "budget",
+          "POSTGRES_PASSWORD": "budget"
+        },
+        "volumes": ["pgdata:/var/lib/postgresql/data"]
+      },
+      "budget-commun": {
+        "image": "budget-commun:latest",
+        "restart": "unless-stopped",
+        "ports": ["23000:3000"],
+        "depends_on": ["db"],
+        "environment": {
+          "DATABASE_URL": "postgres://budget:budget@db:5432/budget",
+          "JWT_SECRET": "changez-cette-valeur"
+        }
+      }
+    },
+    "volumes": { "pgdata": {} }
+  }
+}'
+```
+
+### 3. Mises à jour
+
+```bash
+# Rebuild + transfert
+docker buildx build --platform linux/amd64 -t budget-commun:latest -f backend/Dockerfile .
+docker save budget-commun:latest | ssh admin@<IP-NAS> "sudo docker load"
+
+# Redéployer
+ssh admin@<IP-NAS> "sudo midclt call app.redeploy budget-commun"
+```
+
+---
+
+## Installation sur mobile (PWA)
+
+**iPhone (Safari) :**
+1. Ouvrir l'URL de l'application dans Safari
+2. Appuyer sur **Partager** → **Sur l'écran d'accueil**
+3. Nommer l'app et confirmer
+
+**Android (Chrome) :**
+1. Ouvrir l'URL dans Chrome
+2. Menu → **Ajouter à l'écran d'accueil**
+
+> Les deux appareils doivent être sur le même réseau Wi-Fi que le serveur.
+> Pour un accès depuis l'extérieur, configurez un reverse proxy (Nginx, Traefik) ou un VPN (WireGuard).
+
+---
+
+## Développement local
+
+```bash
+# Backend
+cd backend && npm install
+DATABASE_URL=postgres://budget:budget@localhost:5432/budget node server.js
+
+# Frontend (dans un autre terminal)
+cd frontend && npm install && npm run dev
+```
+
+Le frontend Vite proxifie `/api` vers `http://localhost:3000`.
+
+---
+
+## Sauvegarde
+
+Les données sont dans le volume Docker `pgdata`. Pour sauvegarder :
+
+```bash
+docker exec <container-postgres> pg_dump -U budget budget > backup.sql
+```
+
+Pour restaurer :
+```bash
+docker exec -i <container-postgres> psql -U budget budget < backup.sql
+```