166 lines
6.2 KiB
Markdown
166 lines
6.2 KiB
Markdown
Certamente! Un buon file `README.md` è fondamentale per ogni progetto. Ecco una bozza completa e ben strutturata che puoi adattare. Spiega l'architettura, come iniziare e i comandi più comuni.
|
|
|
|
---
|
|
|
|
# Progetto Monorepo [Nome del Progetto]
|
|
|
|
Questo repository contiene il codice sorgente per [breve descrizione dello scopo del progetto]. È strutturato come una monorepo per facilitare lo sviluppo e la gestione coordinata di frontend e backend.
|
|
|
|
L'ambiente di sviluppo locale è completamente gestito tramite Docker e Docker Compose.
|
|
|
|
## 🚀 Tech Stack
|
|
|
|
- **Frontend**: React (con Vite.js)
|
|
- **Backend**: FastAPI (Python)
|
|
- **Database**: PostgreSQL
|
|
- **Migrazioni DB**: Alembic
|
|
- **Infrastruttura di Sviluppo**: Docker, Docker Compose
|
|
- **Reverse Proxy**: Nginx
|
|
|
|
## 🏗️ Struttura del Progetto
|
|
|
|
La monorepo è organizzata come segue per separare le responsabilità:
|
|
|
|
```
|
|
.
|
|
├── .env.example # Template per le variabili d'ambiente
|
|
├── docker-compose.yml # Orchesterazione dei servizi Docker
|
|
├── packages/ # Contiene il codice sorgente delle applicazioni
|
|
│ ├── backend/ # Servizio FastAPI
|
|
│ └── frontend/ # Applicazione React
|
|
├── proxy/ # Configurazione del reverse proxy Nginx
|
|
└── uploads/ # Directory per lo storage di file (mappata come volume)
|
|
```
|
|
|
|
- **`packages/`**: Contiene i singoli servizi (backend, frontend). Ogni pacchetto è autonomo e ha il suo `Dockerfile` e la gestione delle dipendenze.
|
|
- **`proxy/`**: Contiene la configurazione di Nginx, che funge da unico punto di ingresso per l'applicazione, instradando il traffico verso il frontend o il backend a seconda dell'URL.
|
|
- **`uploads/`**: Una directory persistente, condivisa con il container del backend, per memorizzare i file caricati dagli utenti.
|
|
|
|
---
|
|
|
|
## 🏁 Guida Rapida: Avvio Locale
|
|
|
|
Segui questi passaggi per avviare l'intero stack in ambiente di sviluppo.
|
|
|
|
### Prerequisiti
|
|
|
|
- [Docker](https://www.docker.com/get-started) installato e in esecuzione.
|
|
- [Docker Compose](https://docs.docker.com/compose/install/) (di solito incluso con Docker Desktop).
|
|
- Git.
|
|
|
|
### 1. Clona il Repository
|
|
|
|
```bash
|
|
git clone [URL_DEL_TUO_REPOSITORY]
|
|
cd [NOME_DELLA_CARTELLA]
|
|
```
|
|
|
|
### 2. Configura le Variabili d'Ambiente
|
|
|
|
Copia il file di esempio `.env.example` e crea un file `.env`. Questo file non verrà tracciato da Git ed è sicuro per le tue credenziali locali.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Apri il file `.env` e personalizza i valori se necessario (i valori di default sono pensati per lo sviluppo locale e dovrebbero funzionare subito).
|
|
|
|
### 3. Avvia i Servizi
|
|
|
|
Usa Docker Compose per costruire le immagini e avviare tutti i container.
|
|
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
- Il flag `--build` è necessario la prima volta o ogni volta che modifichi un `Dockerfile` o le dipendenze (es. `package.json` o `pyproject.toml`).
|
|
- Per avviare i container in background, usa il flag `-d`: `docker-compose up -d`.
|
|
|
|
### 4. Accedi all'Applicazione
|
|
|
|
Una volta che tutti i servizi sono in esecuzione, puoi accedere a:
|
|
|
|
- **Frontend**: [http://localhost:8080](http://localhost:8080)
|
|
- **API Backend**: Le richieste del frontend a `/api` vengono automaticamente inoltrate a [http://localhost:8080/api](http://localhost:8080/api)
|
|
|
|
L'ambiente di sviluppo è configurato con **hot-reloading**: qualsiasi modifica al codice nel frontend o nel backend verrà applicata automaticamente senza dover riavviare i container.
|
|
|
|
---
|
|
|
|
## 🛠️ Comandi Utili per lo Sviluppo
|
|
|
|
Questi comandi devono essere eseguiti dalla root del progetto.
|
|
|
|
### Fermare i servizi
|
|
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
Per rimuovere anche i volumi (incluso il database!), usa: `docker-compose down -v`.
|
|
|
|
### Visualizzare i log
|
|
|
|
```bash
|
|
# Log di tutti i servizi in tempo reale
|
|
docker-compose logs -f
|
|
|
|
# Log di un servizio specifico (es. backend)
|
|
docker-compose logs -f backend
|
|
```
|
|
|
|
### Eseguire comandi all'interno di un container
|
|
|
|
Puoi aprire una shell o eseguire un comando specifico in un container in esecuzione.
|
|
|
|
```bash
|
|
# Aprire una shell bash nel container del backend
|
|
docker-compose exec backend bash
|
|
|
|
# Aprire una shell sh nel container del frontend
|
|
docker-compose exec frontend sh
|
|
```
|
|
|
|
### Gestione delle Migrazioni del Database (Alembic)
|
|
|
|
Le migrazioni del database vengono gestite tramite Alembic all'interno del container del backend.
|
|
|
|
1. **Creare una nuova migrazione** (dopo aver modificato i modelli SQLAlchemy in `packages/backend/app/models.py`):
|
|
|
|
```bash
|
|
docker-compose exec backend alembic revision --autogenerate -m "Descrizione della modifica"
|
|
```
|
|
|
|
2. **Applicare le migrazioni** al database:
|
|
|
|
```bash
|
|
docker-compose exec backend alembic upgrade head
|
|
```
|
|
|
|
### Gestire le dipendenze
|
|
|
|
Le dipendenze devono essere aggiunte all'interno del rispettivo container per garantire la coerenza dell'ambiente.
|
|
|
|
- **Aggiungere una dipendenza Python (Backend)**:
|
|
|
|
```bash
|
|
docker-compose exec backend poetry add nome-pacchetto
|
|
```
|
|
|
|
- **Aggiungere una dipendenza Node.js (Frontend)**:
|
|
|
|
```bash
|
|
docker-compose exec frontend npm install nome-pacchetto
|
|
```
|
|
|
|
Dopo aver aggiunto una dipendenza, è buona norma ricostruire l'immagine per essere sicuri che i nuovi pacchetti vengano inclusi correttamente: `docker-compose up --build`.
|
|
|
|
---
|
|
|
|
## 🌐 Endpoint e Servizi
|
|
|
|
| Servizio | URL di accesso locale | Indirizzo interno a Docker | Descrizione |
|
|
| :---------- | :-------------------------------- | :------------------------------------- | :-------------------------------------------------------------- |
|
|
| **Proxy** | `http://localhost:8080` | `proxy:80` | Punto di ingresso unico. |
|
|
| **Frontend**| `http://localhost:8080` | `http://frontend:5173` | Interfaccia utente React (servita tramite Vite dev server). |
|
|
| **Backend** | `http://localhost:8080/api` | `http://backend:8000` | API FastAPI. |
|
|
| **Database**| `localhost:5432` (se esposta) | `db:5432` | Istanza PostgreSQL. | |