Vai al contenuto principale

Self-hosting con Docker

Esegui la tua istanza privata di B1 Admin, del portale membri B1, dell'API e di un database MySQL su qualsiasi macchina con Docker — un server domestico, un VPS da 5$, o una macchina on-prem. Un solo docker compose up costruisce e avvia tutto. Se preferisci non gestire affatto un server, vedi Self-hosting su Railway per l'alternativa gestita.

Avvio rapido​

Cosa ti serve

  • Docker Engine con Compose v2 (incluso in Docker Desktop)
  • ~4 GB di RAM disponibili durante la build iniziale (le app web vengono costruite dal sorgente)
  • Git, oppure semplicemente il file docker-compose.yml grezzo
git clone https://github.com/ChurchApps/B1Admin.git
cd B1Admin
docker compose up -d

La prima esecuzione richiede 10–20 minuti: costruisce B1Admin dal tuo clone e costruisce l'API e B1App direttamente dai loro repository GitHub. Gli avvii successivi richiedono secondi.

Quando tutti e quattro i servizi sono attivi:

  1. Apri http://localhost:3101 (B1 Admin).
  2. Clicca Registrati e crea il tuo account. Il primo account è automaticamente un amministratore del server.
  3. Segui le indicazioni nell'app per creare la tua prima chiesa.

Gli schemi del database vengono creati automaticamente dalla migrazione di avvio del container dell'API — nessun SQL manuale richiesto.

ServizioURL
B1Admin (staff/admin)http://localhost:3101
B1App (portale membri / sito web)http://localhost:3000
APIhttp://localhost:8084
MySQLsolo interno (mysql:3306 sulla rete compose)

Configurazione​

Tutte le impostazioni vivono in un file .env accanto a docker-compose.yml. Ogni variabile ha un valore predefinito funzionante per localhost, quindi il file è opzionale finché non lo personalizzi.

# .env — tutto è opzionale; mostrato con i valori predefiniti
MYSQL_ROOT_PASSWORD=churchapps
JWT_SECRET=please-change-this-jwt-secret
ENCRYPTION_KEY=PleaseChangeThisDockerDefaultKey   # esattamente 32 caratteri

# URL pubblici (cambiali quando esponi oltre localhost)
API_URL=http://localhost:8084
B1ADMIN_URL=http://localhost:3101
B1APP_URL=http://localhost:3000
SOCKET_URL=ws://localhost:8084

# Email — vedi la sezione Email della guida Railway per le procedure guidate dei provider
MAIL_SYSTEM=
SMTP_HOST=
SMTP_USER=
SMTP_PASS=
SMTP_SECURE=false
SUPPORT_EMAIL=noreply@yourchurch.org

Prima dell'uso reale, cambia MYSQL_ROOT_PASSWORD, JWT_SECRET, ed ENCRYPTION_KEY (qualsiasi stringa di 32 caratteri).

Avviso

I valori *_URL sono incorporati nelle app web al momento della build (comportamento standard di Vite/Next.js). Cambiarli in .env richiede una ricostruzione, non solo un riavvio:

docker compose up -d --build

Cambiare la password MySQL dopo il primo avvio richiede l'aggiornamento della password anche dentro MySQL — il volume mantiene le vecchie credenziali.

Esporlo a Internet​

Metti qualsiasi reverse proxy davanti e assegna a ogni servizio un hostname. Con Caddy è così:

admin.yourchurch.org { reverse_proxy localhost:3101 }
app.yourchurch.org   { reverse_proxy localhost:3000 }
api.yourchurch.org   { reverse_proxy localhost:8084 }

Poi imposta gli URL in .env e ricostruisci:

API_URL=https://api.yourchurch.org
B1ADMIN_URL=https://admin.yourchurch.org
B1APP_URL=https://app.yourchurch.org
SOCKET_URL=wss://api.yourchurch.org
docker compose up -d --build

Il WebSocket usato per la chat e le notifiche live condivide la porta dell'API, quindi SOCKET_URL è semplicemente l'URL dell'API con wss://.

Email, contributi, multi-sito e integrazioni​

Questi funzionano in modo identico alla distribuzione Railway — le stesse variabili d'ambiente, impostate nel tuo file .env invece che nella dashboard Railway (il file compose le passa all'API):

  • Email / SMTP — fortemente consigliato; senza email i membri non possono reimpostare le password
  • Multi-sito — chiese illimitate per istanza, gestite nell'interfaccia amministrativa
  • Contributi online — configurati per chiesa nell'interfaccia amministrativa, non tramite variabili d'ambiente
  • Integrazioni facoltative — OPENAI_API_KEY, YOUTUBE_API_KEY, PEXELS_KEY, VIMEO_TOKEN, API_BIBLE_KEY, WEB_PUSH_PUBLIC_KEY/WEB_PUSH_PRIVATE_KEY, GOOGLE_RECAPTCHA_SECRET_KEY

Dati, backup e archiviazione file​

Due volumi Docker denominati contengono tutto lo stato:

VolumeContenuto
mysql-dataTutti gli schemi del database
api-contentFile caricati — foto, documenti, immagini del sito (montato su /app/content)

Fai il backup del database con una riga sola (schedulala con cron):

docker compose exec mysql mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases > backup-$(date +%F).sql

Fai il backup dei file caricati copiando il volume:

docker run --rm -v b1admin_api-content:/data -v "$PWD":/backup alpine tar czf /backup/content-$(date +%F).tgz -C /data .

Per librerie multimediali di grandi dimensioni puoi passare l'archiviazione dei file a S3 invece del volume locale — imposta FILE_STORE=S3 più le variabili AWS_* descritte nella sezione Archiviazione file della guida Railway.

Aggiornamento​

L'API e B1App si costruiscono dal branch main dei loro repository GitHub; B1Admin si costruisce dal tuo clone locale.

git pull                              # aggiorna B1Admin
docker compose build --pull           # ricostruisci tutte le immagini contro l'ultimo main
docker compose up -d

Le migrazioni del database vengono eseguite automaticamente all'avvio del container dell'API.

Per fissare le versioni invece di seguire main, punta i contesti di build a un tag in .env:

API_CONTEXT=https://github.com/ChurchApps/Api.git#v1.2.3
B1APP_CONTEXT=https://github.com/ChurchApps/B1App.git#v1.2.3

Gli sviluppatori possono puntare le stesse variabili a checkout locali (ad es. API_CONTEXT=../Api).

Risoluzione dei problemi​

SintomoCausa probabileSoluzione
Il container api si riavvia in loopMySQL non pronto o migrazione fallitadocker compose logs api — la migrazione stampa quale modulo è fallito
Il login reindirizza a api.churchapps.orgApp web costruita senza gli argomenti dello stage customRicostruisci: docker compose build --no-cache b1admin b1app
Cambiato un URL in .env ma non è successo nullaGli URL sono incorporati al momento della builddocker compose up -d --build
"Controlla la tua email" ma nessuna email arrivaMAIL_SYSTEM=SMTP con credenziali errateCorreggi le credenziali, o rimuovi MAIL_SYSTEM per disabilitare l'email
Chat / funzioni live silenzioseSOCKET_URL irraggiungibile dal browserDeve essere wss:// dietro HTTPS e proxato alla porta 8084
La build muore su un piccolo VPSMemoria esaurita durante next buildAggiungi swap, oppure costruisci su un'altra macchina e usa docker save/load

Ancora bloccato? Apri un issue su github.com/ChurchApps/ChurchAppsSupport/issues con l'output di docker compose logs.

Articoli correlati​