realNIS

Applicazione full-stack per questionari NIS2 con:

• backend Spring Boot (API + PDF)
• frontend React/Vite servito da Nginx
• PostgreSQL

Stack

• Backend: Java 21, Spring Boot 3.3.2, JPA/Hibernate, PostgreSQL
• Frontend: React 19, Vite 7, Tailwind
• Runtime: Docker Compose

Struttura repository

• backend/: API Spring Boot
• frontend/: UI React/Vite
• backend/migrations/: migrazioni SQL principali
• docker-compose.yml: stack completo (postgres + backend + frontend)

Requisiti

• Docker + Docker Compose plugin
• (solo sviluppo locale senza Docker) Java 21 e Node/NPM

Configurazione .env

Backend (backend/.env)

Esempio:

DB_HOST=postgres
DB_PORT=5432
DB_NAME=realnis
DB_USER=realnis
DB_PASSWORD=realnis
AUTH_ENABLED=false

Note:

• in Docker Compose le variabili DB sono già passate dal file compose al container backend
• AUTH_ENABLED=false disabilita autenticazione (utile in sviluppo)

Frontend (frontend/.env)

Esempio:

VITE_API_HOST=/api
VITE_API_PROXY_TARGET=http://localhost:8080

Note:

• in produzione Docker, il frontend Nginx usa /api come proxy verso backend:8080
• in sviluppo Vite, il proxy /api usa VITE_API_PROXY_TARGET

Avvio rapido con Docker (consigliato)

1. Build e avvio servizi:

docker compose up -d --build

2. Applica le migrazioni SQL (obbligatorio se DB non allineato):

for f in backend/migrations/*.sql; do
  echo "Applying $f"
  docker compose exec -T postgres psql -U realnis -d realnis < "$f"
done

3. Riavvia backend:

docker compose restart backend

4. Verifica stato:

docker compose ps
docker compose logs --tail=100 backend

URL:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8080
• Swagger: http://localhost:8080/swagger-ui/index.html

Perché servono le migrazioni

Il backend usa:

• spring.jpa.hibernate.ddl-auto=validate

quindi non crea/aggiorna lo schema automaticamente.
Se lo schema non è aggiornato, il backend va in crash e il frontend restituisce 502 Bad Gateway sulle chiamate /api/*.

Avvio locale senza Docker

1) Database

Avvia solo Postgres:

docker compose up -d postgres

2) Backend

cd backend
./mvnw spring-boot:run

3) Frontend

cd frontend
npm install
npm run dev

Frontend dev: http://localhost:5173

Endpoint principali

• GET /api/ping
• POST /api/register
• POST /api/login
• POST /api/password_reset/request
• POST /api/password_reset/confirm
• GET /api/get_questions
• POST /api/get_answers
• GET /api/get_valutazione
• POST /api/valutazione
• POST /api/valutazione/pdf
• GET /api/pre_questionario

Endpoint admin:

• POST /api/admin/reload_questions
• POST /api/admin/reload_infos
• POST /api/admin/reload_valutazione_config

Deploy su server (procedura consigliata)

1. Aggiorna codice:

git pull

2. Ricrea immagini:

docker compose up -d --build

3. Applica migrazioni pendenti:

for f in backend/migrations/*.sql; do
  docker compose exec -T postgres psql -U realnis -d realnis < "$f"
done

4. Riavvia backend:

docker compose restart backend

5. Verifica:

docker compose ps
docker compose logs --tail=200 backend

Troubleshooting

Errore failed to read dockerfile: open Dockerfile: no such file or directory

Causa: compose punta a Dockerfile sbagliato.
Fix già applicata: docker-compose.yml usa backend/Dockerfile.

Errore 502 Bad Gateway in registrazione/login

Causa tipica: backend non raggiungibile (crash).
Controlli:

docker compose ps -a
docker compose logs --tail=200 backend
docker compose logs --tail=200 frontend

Se nei log backend vedi errori schema (es. colonna mancante), applica le migrazioni e riavvia backend.

Backend Exited (1) con schema validation error

Esegui:

for f in backend/migrations/*.sql; do
  docker compose exec -T postgres psql -U realnis -d realnis < "$f"
done
docker compose restart backend

Comandi utili

• Avvio: docker compose up -d --build
• Stop: docker compose down
• Stop + rimozione volumi DB: docker compose down -v
• Stato: docker compose ps
• Log backend: docker compose logs -f backend
• Log frontend: docker compose logs -f frontend
• Log postgres: docker compose logs -f postgres

Note importanti

• Le credenziali DB nel compose (realnis/realnis) sono adatte a sviluppo: in produzione cambiale.
• Per un deploy più robusto conviene integrare Flyway/Liquibase per migrazioni automatiche.
• Documentazione di dettaglio per backend e frontend è disponibile anche in:
  • backend/README.md
  • frontend/README.md