Vai al contenuto

Deploy in produzione

Jinbocho si distribuisce come stack self-hosted sul tuo server. Documentato qui sotto: il modo più veloce per ottenere uno stack funzionante, seguito dalla versione completamente manuale, passo per passo, per quando vuoi controllare ogni singolo pezzo.

Tutto il tooling di deployment (file compose, template env, script) si trova in jinbocho-install-community-v1.

Deploy self-hosted

Quick start

Un solo comando trasforma un server Debian/Ubuntu appena creato in uno stack Jinbocho completamente funzionante: un unico database Postgres, i tre servizi backend, il frontend e Caddy come reverse proxy con HTTPS automatico.

git clone https://github.com/jinbocho/jinbocho-install-community-v1.git
cd jinbocho-install-community-v1

sudo ./scripts/setup-vps-community.sh \
  --domain library.example.com \
  --email you@example.com \
  --google-books-key AIza...

Requisiti:

  • Un server Debian/Ubuntu appena creato, con IP pubblico, eseguito come root (o con sudo).
  • --domain deve già risolvere all'IP del server — Caddy richiede un certificato Let's Encrypt per quel dominio al primo avvio. Ometti del tutto --domain/--email per servire in HTTP semplice sull'IP nudo (senza TLS).
  • Ogni opzione non passata come flag viene chiesta interattivamente. Aggiungi --non-interactive per saltare tutti i prompt e affidarti solo a flag/default — utile per installazioni non presidiate (es. cloud-init).

Nel giro di un paio di minuti lo script stampa l'URL del frontend, l'URL dell'API gateway e dove sono stati scritti i segreti. Apri il frontend e registra la prima famiglia — diventa l'account admin.

Ri-eseguirlo è sicuro

Lo script è idempotente: i segreti esistenti, i file envs/*.env e il Caddyfile generato vengono mantenuti così come sono a una seconda esecuzione, a meno che tu non li elimini prima.

Cosa fa lo script

scripts/setup-vps-community.sh esegue docker/docker-compose.all.yml end to end:

  1. Installa Docker (via get.docker.com) se non è già presente.
  2. Opzionalmente configura ufw per aprire 22/80/443 (--enable-firewall).
  3. Clona (o aggiorna) jinbocho-fe accanto al repository infrastruttura.
  4. Genera POSTGRES_PASSWORD, JWT_SECRET_KEY e INTERNAL_SERVICE_TOKEN, e scrive ogni file envs/*.env a partire dai template *.example.
  5. Scrive un Caddyfile che fa da reverse proxy per /api/* verso il gateway e per tutto il resto verso il frontend, con TLS automatico se è stato indicato --domain.
  6. Scarica le immagini backend, builda l'immagine del frontend dal sorgente e avvia l'intero stack con docker compose ... up -d.
  7. Interroga /health attraverso il gateway e segnala se lo stack si è avviato correttamente.

Tutte le opzioni dello script

Flag Valore Default Descrizione
--domain <fqdn> — (usa l'IP del server, solo HTTP) Dominio pubblico già puntato a questo server. Abilita HTTPS automatico.
--email <email> — Email di contatto per Let's Encrypt. Obbligatoria se è impostato --domain.
--google-books-key <key> — Chiave API Google Books, usata per la ricerca ISBN nel catalogo. Può essere aggiunta in seguito modificando envs/catalog-service.env.
--smtp-user <indirizzo Gmail> — Indirizzo Gmail usato per inviare le email di invito/reset password. Host e porta SMTP vengono impostati automaticamente. Lascia vuoto per registrare il link nei log invece di inviarlo.
--smtp-password <app password> — App Password Gmail per --smtp-user — non la password normale dell'account.
--email-from <email> valore di --smtp-user Indirizzo mittente mostrato sulle email in uscita.
--netdata-enabled true|false chiesto interattivamente Abilita la dashboard Netdata locale (metriche host + per-container, :19999, solo localhost). Nessun account o segreto necessario. Opzionale, disabilitato di default.
--frontend-base-url <url> derivato da --domain/IP del server URL pubblico del frontend incluso nei link delle email.
--fe-repo <git url> jinbocho/jinbocho-fe Repository del frontend da clonare.
--fe-branch <branch> main Branch del frontend da clonare.
--version <tag> latest Tag dell'immagine da scaricare per i servizi backend.
--enable-firewall flag disattivato Configura e abilita ufw, aprendo le porte 22/80/443.
--skip-docker-install flag disattivato Non tentare di installare Docker (usalo se è già presente tramite altro tooling).
--non-interactive flag disattivato Non chiedere mai nulla; usa solo i flag/default forniti.
-h, --help flag — Stampa l'elenco completo dei flag ed esce.

Verifica del deployment

./scripts/validate-api.sh

Registra una famiglia di test ed esercita gli endpoint principali tramite il gateway (http://localhost:8000, o il tuo dominio).

Comandi utili per la gestione quotidiana (lo script stampa l'invocazione esatta per la tua configurazione, incluso --profile observability se Netdata è abilitato):

docker compose -f docker/docker-compose.all.yml --env-file .env logs -f   # segui i log
docker compose -f docker/docker-compose.all.yml --env-file .env ps        # stato dei servizi
docker compose -f docker/docker-compose.all.yml --env-file .env down      # ferma tutto (dati/volumi mantenuti)

Installazione manuale (senza script)

Se preferisci non eseguire lo script automatico — ad esempio per rivedere ogni file prima che venga scritto, o perché gestisci già il TLS con un tuo reverse proxy — installa pezzo per pezzo con docker-compose.community.yml:

git clone https://github.com/jinbocho/jinbocho-install-community-v1.git
cd jinbocho-install-community-v1

cp .env.example .env
cp envs/auth-service.env.example envs/auth-service.env
cp envs/catalog-service.env.example envs/catalog-service.env
cp envs/api-gateway.env.example envs/api-gateway.env

# modifica i file sopra — vedi le tabelle dei campi qui sotto

docker compose -f docker/docker-compose.community.yml up -d

Nessun TLS o reverse proxy in questa modalità

A differenza dello script in un passaggio, docker-compose.community.yml non avvia Caddy. Il gateway è esposto direttamente sulla porta 8000. Metti un tuo reverse proxy (Caddy, nginx, Traefik, un load balancer) davanti se ti serve HTTPS o un nome di dominio.

.env (radice del repository, letto da Docker Compose stesso):

Variabile Default Obbligatoria Descrizione
POSTGRES_PASSWORD change_me_local_dev Sì Password per i container Postgres locali. Cambiala prima di esporre qualcosa pubblicamente.
JINBOCHO_VERSION latest No Tag dell'immagine da scaricare per i servizi backend.

envs/auth-service.env:

Variabile Obbligatoria Descrizione
DEBUG No Imposta false in produzione; true abilita anche il logging SQL.
DATABASE_URL Sì postgresql+asyncpg://auth_role:<POSTGRES_PASSWORD>@postgres:5432/jinbocho — il servizio compose postgres, database jinbocho, schema auth. La password coincide con POSTGRES_PASSWORD del .env radice.
JWT_SECRET_KEY Sì Deve essere identica su auth-service, catalog-service e api-gateway. Genera con openssl rand -hex 32.
INTERNAL_SERVICE_TOKEN Sì Deve coincidere con il valore di catalog-service — autentica le chiamate catalog→auth (email di promemoria prestiti). Genera con openssl rand -hex 32.
FRONTEND_BASE_URL No Usato per costruire i link nelle email di invito/reset password.
SMTP_USER / SMTP_PASSWORD No Lascia vuoti per registrare i link di invito/reset nei log invece di inviarli via email.

envs/catalog-service.env:

Variabile Obbligatoria Descrizione
DATABASE_URL Sì postgresql+asyncpg://catalog_role:<POSTGRES_PASSWORD>@postgres:5432/jinbocho — schema catalog.
JWT_SECRET_KEY Sì Identica al valore di auth-service.
INTERNAL_SERVICE_TOKEN Sì Identica al valore di auth-service.
GOOGLE_BOOKS_API_KEY Consigliata Chiave gratuita su console.cloud.google.com. Senza, la quota condivisa (1000 richieste/giorno) si esaurisce rapidamente.

envs/api-gateway.env:

Variabile Obbligatoria Descrizione
JWT_SECRET_KEY Sì Identica al valore di auth-service.
CORS_ORIGINS No ["*"] di default — imposta l'URL reale del tuo frontend in produzione.

Apri http://<ip-server>:8000/docs per confermare che il gateway sia attivo, poi procedi come descritto in Verifica del deployment qui sopra.

Opzionale: metriche (Netdata)

Disabilitato di default — salta questa sezione se non ti serve, lo stack funziona esattamente come descritto sopra anche senza. Quando abilitato (--netdata-enabled true, oppure a mano in seguito con --profile observability), un unico container Netdata monitora CPU/RAM/ disco/rete host + per-container con una dashboard integrata. Nessun account esterno, nessun segreto da configurare. La dashboard è legata solo a 127.0.0.1:19999 — raggiungila con ssh -L 19999:localhost:19999 <host>, poi http://localhost:19999. Vedi README.md (sezione 6) in jinbocho-install-community-v1 per la configurazione completa.

Prossimi passi