Installazione & Setup

Guida completa per installare e configurare Il Carrubo dal setup iniziale fino al primo avvio.

Installazione del progetto

Setup Supabase

Il Carrubo utilizza Supabase come database PostgreSQL, sistema di autenticazione e storage. Segui questi passi per configurare il tuo progetto.

Crea un progetto Supabase

  1. Vai su supabase.com e accedi (o crea un account)
  2. Clicca su New Project
  3. Scegli un nome (es. il-carrubo), una password sicura per il database e la regione più vicina (es. eu-central-1)
  4. Attendi il completamento del provisioning (circa 1-2 minuti)

Recupera le credenziali

Nella dashboard del tuo progetto Supabase, vai in Settings → API e copia:

Credenziale Dove trovarla Variabile .env
Project URL Settings → API → Project URL SUPABASE_URL
Anon Key Settings → API → anon public SUPABASE_KEY
Service Role Key Settings → API → service_role secret SUPABASE_SERVICE_ROLE_KEY
Database URL Settings → Database → Connection string (URI) SUPABASE_DB_URL

::: callout[warning]
La Service Role Key ha accesso completo al database, bypassando le Row Level Security policies. Non esporla mai lato client.
:::

Configura il database

Il Carrubo necessita delle seguenti tabelle principali. Puoi crearle tramite l’SQL Editor di Supabase oppure utilizzando lo script di migrazione incluso nel progetto.

Tabelle del database

Tabella Descrizione
prenotazioni Prenotazioni con date, stato, prezzi e riferimenti ospiti
ospiti Anagrafica ospiti con dati documento, nazionalità e MRZ
impostazioni Configurazione del sistema (nome struttura, codici, feature flags)
documenti Metadati documenti scansionati e relativi URL di storage
alloggiati_log Log degli invii alla Questura tramite Alloggiati Web
tariffe Tariffe per tipologia di camera e periodo
camere Anagrafica camere con tipologia, capacità e stato
utenti Utenti del sistema con ruoli e permessi
statistiche Dati aggregati per la dashboard analytics
email_log Log delle email inviate agli ospiti

::: callout[note]
Le migrazioni SQL si trovano nella directory del progetto. Consulta il file README.md per le istruzioni specifiche di migrazione del database.
:::

Primo avvio

Dopo aver configurato le variabili d’ambiente, avvia il server:

npm run dev

Cosa aspettarsi

Al primo avvio vedrai la GUI del terminale basata su blessed, che mostra:

┌─────────────────── Il Carrubo PMS ───────────────────┐
│                                                       │
│  ✅ Server avviato sulla porta 3000                   │
│  ✅ Connessione Supabase stabilita                    │
│  ✅ Route API caricate (46 endpoint)                  │
│  📊 Dashboard attiva                                  │
│                                                       │
│  Log in tempo reale...                                │
│                                                       │
└───────────────────────────────────────────────────────┘

La GUI mostra in tempo reale:

  • Log delle richieste HTTP in entrata
  • Stato delle connessioni al database
  • Statistiche di utilizzo (richieste/minuto, memoria, CPU)
  • Errori evidenziati in rosso per un debug rapido

Modalità di avvio

Comando Descrizione
npm run dev Sviluppo con nodemon + GUI terminale
npm start Produzione standard
node server.js Avvio diretto senza nodemon

Troubleshooting

::: callout[warning]

Errore: SUPABASE_URL is not defined

Il file .env non è stato trovato o le variabili non sono state caricate. Verifica che:

  • Il file .env esista nella root del progetto
  • Le variabili SUPABASE_URL e SUPABASE_KEY siano impostate
  • Non ci siano spazi attorno al segno =
    :::

::: callout[warning]

Errore: EADDRINUSE: port 3000 already in use

La porta 3000 è già occupata da un altro processo. Puoi:

  • Terminare il processo che occupa la porta: npx kill-port 3000
  • Cambiare la porta nel file .env: PORT=3001
    :::

::: callout[warning]

Errore: connection refused al database

La connessione a Supabase non riesce. Controlla:

  • Che il SUPABASE_DB_URL sia corretto e includa la password
  • Che il progetto Supabase sia attivo (non in pausa)
  • Che la tua rete non blocchi le connessioni PostgreSQL (porta 5432)
    :::

::: callout[warning]

Le dipendenze non si installano

Problemi con npm install:

  • Verifica la versione di Node.js: node -v (deve essere >= 18)
  • Prova a cancellare node_modules e package-lock.json, poi riesegui npm install
  • Su Windows, avvia il terminale come amministratore
    :::

::: callout[tip]
Se riscontri altri problemi, apri una issue sul repository GitHub con i log dell’errore e la configurazione del tuo ambiente.
:::

Previous Quick Start Next Variabili d'Ambiente