Vai al contenuto

Prerequisiti

Prima di installare Jinbocho in locale o in produzione, assicurati che il tuo sistema soddisfi i seguenti requisiti.

Sistema operativo

Jinbocho funziona su: - Linux (Ubuntu 22.04 LTS o superiore, Debian 12+) - macOS (12.0 o superiore, Intel o Apple Silicon) - Windows 11 (WSL2 con Ubuntu 22.04)

Utenti Windows: configurazione WSL2

Se sei su Windows, usa Windows Subsystem for Linux 2:

# Installa WSL2 con Ubuntu 22.04
wsl --install -d Ubuntu-22.04

# Nel terminale WSL, verifica che siano disponibili almeno 4 GB di RAM
free -h

Docker & Docker Compose

Docker Desktop o Docker Engine v20.10+ con Docker Compose v2.20+

Installazione

macOS (Homebrew): 

brew install docker docker-compose

Linux (Ubuntu/Debian): 

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Verifica: 

docker --version      # v20.10.0 o superiore
docker compose version  # v2.20.0 o superiore

Python 3.12

Tutti i servizi backend richiedono Python 3.12 o superiore.

Installazione

macOS (Homebrew): 

brew install python@3.12
python3.12 --version

Linux (Ubuntu/Debian): 

sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev
python3.12 --version

Windows (WSL2): 

sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

Node.js 18+

Lo sviluppo del frontend richiede Node.js 18.0.0 o superiore con npm 9.0.0 o superiore.

Installazione

macOS (Homebrew): 

brew install node@18
node --version   # v18.x.x
npm --version    # 9.x.x o superiore

Linux/WSL2: 

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version
npm --version

Git

Necessario per clonare i repository.

macOS: 

brew install git

Linux/WSL2: 

sudo apt install git

Verifica: 

git --version

Client PostgreSQL (psql)

Facoltativo ma consigliato per ispezionare il database locale.

macOS: 

brew install postgresql

Linux/Ubuntu: 

sudo apt install postgresql-client

Chiavi API esterne (facoltative)

Per la ricerca ISBN avanzata, considera di ottenere:

Google Books API Key

  • Perché: fallback per i metadati ISBN quando Open Library è lento
  • Costo: livello gratuito (100 richieste/giorno)
  • Come ottenerla: https://developers.google.com/books/docs/v1/using#APIKey
  • Quando serve: imposta GOOGLE_BOOKS_API_KEY nel file .env

OpenAI API Key

  • Perché: per il servizio AI (suggerimenti di tag, deduplicazione)
  • Costo: pay-as-you-go (funzione opzionale)
  • Come ottenerla: https://platform.openai.com/api-keys
  • Quando serve: imposta OPENAI_API_KEY se distribuisci ai-service

Account cloud (solo produzione)

Per il deploy su Render + Neon:

Account Neon.tech

  • Scopo: database PostgreSQL gestito
  • Costo: livello gratuito (0,5 GB, sospensione automatica dopo 30 giorni di inattività)
  • Registrazione: https://neon.tech
  • Perché: migliore di Render Postgres (che è effimero)

Account Render.com

  • Scopo: hosting dei servizi backend + frontend
  • Costo: livello gratuito (cold start accettabili), Starter a $7/mese per servizio
  • Registrazione: https://render.com
  • Perché: deploy Docker semplice, integrazione GitHub, SSL integrato

Checkout dei repository

Crea una cartella di lavoro e clona tutti i repository Jinbocho dall’organizzazione GitHub:

mkdir -p ~/workspace/jinbocho && cd ~/workspace/jinbocho

# Clona tutti i repository Jinbocho
git clone https://github.com/jinbocho/jinbocho-infrastructure-v1.git
git clone https://github.com/jinbocho/jinbocho-auth-v1.git
git clone https://github.com/jinbocho/jinbocho-catalog-v1.git
git clone https://github.com/jinbocho/jinbocho-api-gateway-v1.git
git clone https://github.com/jinbocho/jinbocho-ai-v1.git
git clone https://github.com/jinbocho/jinbocho-fe.git

# Verifica che tutti i servizi siano presenti
ls | grep jinbocho
# Atteso: jinbocho-auth-v1  jinbocho-catalog-v1  jinbocho-api-gateway-v1
#         jinbocho-ai-v1  jinbocho-fe  jinbocho-infrastructure-v1

Tutti i repository si trovano nell’organizzazione GitHub jinbocho: https://github.com/jinbocho

Script di verifica dei prerequisiti

Esegui questo script per verificare che tutti i prerequisiti siano installati:

#!/bin/bash
echo "=== Verifica prerequisiti Jinbocho ==="
echo "OS: $(uname -s)"
echo "Docker: $(docker --version)"
echo "Docker Compose: $(docker compose version)"
echo "Python: $(python3.12 --version)"
echo "Node.js: $(node --version)"
echo "npm: $(npm --version)"
echo "Git: $(git --version)"
echo "psql: $(psql --version 2>/dev/null || echo 'Non installato')"
echo "✅ Tutti i prerequisiti sono installati!"

Prossimi passi

Una volta verificati tutti i prerequisiti: 1. Vai a Sviluppo Locale per configurare l’ambiente di sviluppo 2. Per il deploy in produzione, vedi Deploy in Produzione