diff --git a/README.md b/README.md index 98899a7..6ad8560 100644 --- a/README.md +++ b/README.md @@ -5,24 +5,17 @@ Sistema di gestione task per misurazioni con calibro manuale. Soluzione tablet-f ## Architettura ``` -┌─────────────┐ ┌──────────────┐ ┌──────────┐ -│ Browser / │────▶│ Nginx │────▶│ MySQL │ -│ Tablet │ │ (Reverse │ │ 8.0 │ -└─────────────┘ │ Proxy) │ └────▲─────┘ - └──┬───────┬───┘ │ - │ │ │ - ┌─────▼──┐ ┌──▼──────┐ │ - │ Flask │ │ FastAPI │───────┘ - │ Client │ │ Server │ - │ :5000 │ │ :8000 │ - └─────────┘ └─────────┘ +Browser/Tablet → Reverse Proxy → Flask Client (:5000) → FastAPI Server (:8000) → MySQL 8.0 ``` +Due modalità di deployment: +- **Sviluppo** (`docker-compose.dev.yml`): Nginx reverse proxy, porta 80 +- **Produzione** (`docker-compose.yml`): Traefik reverse proxy con SSL automatico (Let's Encrypt) + Il sistema è composto da: -- **Flask Client**: Frontend tablet-oriented con interfaccia responsive +- **Flask Client**: Frontend tablet-oriented con rendering server-side - **FastAPI Server**: Backend API REST con autenticazione via API key -- **Nginx**: Reverse proxy per routing unificato -- **MySQL**: Database relazionale per persistenza dati +- **MySQL 8.0**: Database relazionale per persistenza dati ## Stack Tecnologico @@ -38,11 +31,10 @@ Il sistema è composto da: ### Frontend (Client) - **Flask 3.0**: Framework web per rendering server-side - **Jinja2**: Template engine -- **htmx 2.0**: Interazioni AJAX dichiarative - **Alpine.js 3.x**: Reattività leggera lato client - **TailwindCSS 3.x**: Framework CSS utility-first - **Plotly.js**: Libreria grafici interattivi -- **Fabric.js 5.x**: Editor annotazioni su disegni tecnici +- **Fabric.js 5.3.1**: Editor annotazioni su disegni tecnici - **Flask-Babel**: Sistema i18n per IT/EN ### Sicurezza e Auth @@ -64,7 +56,9 @@ cp .env.example .env # Modifica .env con le tue credenziali (DB, password admin, ecc.) # 3. Avvio dei servizi -docker compose up -d +docker compose -f docker-compose.dev.yml up -d # Sviluppo (Nginx, porta 80) +# oppure +docker compose up -d # Produzione (Traefik, SSL) # 4. Setup iniziale # Apri http://localhost/api/setup nel browser @@ -192,7 +186,7 @@ TieMeasureFlow/ │ └── templates/ # Template HTML per setup page ├── client/ # Flask Frontend (UI tablet) │ ├── app.py # Entry point applicazione -│ ├── blueprints/ # Route blueprints (auth, maker, measurement, metrologist) +│ ├── blueprints/ # Route blueprints (auth, maker, measure, statistics, admin) │ ├── services/ # API client wrapper per chiamate a FastAPI │ ├── templates/ # Jinja2 templates per rendering pagine │ ├── static/ # Asset statici (CSS, JS, immagini) @@ -200,11 +194,12 @@ TieMeasureFlow/ │ │ ├── js/ # Alpine.js components e utility │ │ └── images/ # Loghi, icone, placeholder │ └── translations/ # File i18n per IT/EN (Flask-Babel) -├── nginx/ # Configurazione reverse proxy -│ └── nginx.conf # Routing unificato client/server -├── docker-compose.yml # Orchestrazione servizi Docker -├── .env.example # Template variabili d'ambiente -└── docs/ # Documentazione tecnica +├── nginx/ # Configurazione reverse proxy (dev) +│ └── nginx.conf # Routing unificato client/server +├── docker-compose.yml # Produzione (Traefik, SSL) +├── docker-compose.dev.yml # Sviluppo (Nginx, porta 80) +├── .env.example # Template variabili d'ambiente +└── docs/ # Documentazione tecnica ``` ## Ruoli Utente @@ -234,7 +229,7 @@ Analista qualità con accesso alle statistiche: - Export report PDF con WeasyPrint - Analisi tendenze e capability del processo -I ruoli sono configurabili in fase di creazione utente e possono essere combinati. Flag `is_admin` separato per gestione sistema. +I ruoli sono configurabili in fase di creazione utente e possono essere combinati. Flag `is_admin` separato per gestione sistema (CRUD utenti, cambio password, attivazione/disattivazione account). ## Guida VPS Deployment @@ -263,6 +258,8 @@ newgrp docker ### Deploy Applicazione +Il compose di produzione (`docker-compose.yml`) usa Traefik come reverse proxy con SSL automatico. Richiede un'istanza Traefik già configurata con rete Docker `root_default`. + ```bash # Clone repository git clone @@ -273,13 +270,13 @@ cp .env.example .env nano .env # Modifica almeno: -# - MYSQL_ROOT_PASSWORD -# - MYSQL_PASSWORD -# - SECRET_KEY -# - API_KEY_ADMIN +# - DB_ROOT_PASSWORD +# - DB_PASSWORD +# - SERVER_SECRET_KEY +# - CLIENT_SECRET_KEY # - SETUP_PASSWORD -# Avvia servizi +# Avvia servizi (produzione con Traefik) docker compose up -d # Verifica stato @@ -312,34 +309,18 @@ sudo ufw status ``` 3. Attendi propagazione DNS (5-30 minuti) -### SSL con Certbot (HTTPS) +### SSL (HTTPS) -```bash -# Installa Certbot -sudo apt update -sudo apt install certbot +Il compose di produzione usa Traefik con Let's Encrypt per certificati SSL automatici. Configurare il dominio nelle labels Traefik di `docker-compose.yml`. -# Genera certificati (usa il tuo dominio) -sudo certbot certonly --webroot -w /var/www/certbot -d yourdomain.com -d www.yourdomain.com - -# Decommentare linee SSL in nginx/nginx.conf -nano nginx/nginx.conf -# Rimuovi commenti (#) dalle righe: -# listen 443 ssl http2; -# ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; -# ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; - -# Riavvia nginx -docker compose restart nginx - -# Verifica rinnovo automatico -sudo certbot renew --dry-run -``` - -Accesso produzione: https://yourdomain.com +Per ambienti senza Traefik (compose dev con Nginx), configurare SSL manualmente: +- Impostare `SSL_CERTFILE` e `SSL_KEYFILE` in `.env` +- Decommentare le righe SSL in `nginx/nginx.conf` ## Comandi Utili +> **Nota:** Per sviluppo locale aggiungere `-f docker-compose.dev.yml` ai comandi docker compose. + | Comando | Descrizione | |---------|-------------| | `docker compose up -d` | Avvia tutti i servizi in background | @@ -347,12 +328,10 @@ Accesso produzione: https://yourdomain.com | `docker compose logs -f server` | Segui log del server in tempo reale | | `docker compose logs -f client` | Segui log del client in tempo reale | | `docker compose ps` | Mostra stato di tutti i servizi | -| `docker compose exec server alembic upgrade head` | Esegui migrazioni database | -| `docker compose exec server alembic revision --autogenerate -m "description"` | Genera nuova migrazione | -| `docker compose restart nginx` | Riavvia solo nginx | +| `docker compose exec server alembic -c migrations/alembic.ini upgrade head` | Esegui migrazioni database | +| `docker compose exec server alembic -c migrations/alembic.ini revision --autogenerate -m "desc"` | Genera nuova migrazione | | `docker compose build --no-cache` | Ricostruisci tutte le immagini senza cache | | `docker compose exec mysql mysql -u root -p tiemeasureflow` | Accedi alla CLI MySQL | -| `docker compose exec server python -c "from config import settings; print(settings.database_url)"` | Verifica configurazione server | ## Sviluppo @@ -363,26 +342,28 @@ Accesso produzione: https://yourdomain.com ### Migrazioni Database ```bash -# Genera nuova migrazione cd server -alembic revision --autogenerate -m "Descrizione modifica" + +# Genera nuova migrazione +alembic -c migrations/alembic.ini revision --autogenerate -m "Descrizione modifica" # Applica migrazioni -alembic upgrade head +alembic -c migrations/alembic.ini upgrade head # Rollback ultima migrazione -alembic downgrade -1 +alembic -c migrations/alembic.ini downgrade -1 ``` ### Testing ```bash -# Test server (da implementare) -cd server -pytest +# Server (SQLite in-memory, no MySQL richiesto) +cd server && pytest # Tutti i test +cd server && pytest tests/test_auth.py # Singolo modulo +cd server && pytest tests/test_auth.py::test_login_success # Singolo test +cd server && pytest --cov # Con copertura -# Test client (da implementare) -cd client -pytest +# Client +cd client && pytest ``` ## Licenza