Gestione del self-hosting (aggiornamenti, backup, env, monitoraggio)
Questo manuale è per chi usa The-Y CRM in self-hosting, con una chiave a pagamento o gratuita. Copre la gestione di tutti i giorni: lo stack Docker, gli aggiornamenti, backup e ripristino, le variabili d'ambiente principali, reverse proxy/TLS, il monitoraggio e la licenza. Per la prima installazione e il dimensionamento del server vedi Installazione e requisiti del server.
Lo stack in breve
The-Y gira come stack Docker Compose. I servizi:
| Servizio | A cosa serve |
|---|---|
app | la web app (Next.js), in ascolto internamente sulla porta 3000 |
worker | job in background (recupero email, promemoria, pulizie periodiche, pianificatore delle automazioni) |
postgres | database (tutti i dati dei tenant) |
redis | coda dei job (BullMQ) |
minio | archivio file/media (allegati, registrazioni), compatibile S3 |
caddy | reverse proxy con HTTPS automatico |
watchtower | solo installazioni precedenti alla 1.1.53: aggiornamento automatico facoltativo (pull notturno delle immagini); dalla 1.1.53 aggiorna update.sh nella cartella di installazione (Aggiornamenti) |
configurati dall'installer, se vuoi: asterisk, coturn | centralino e TURN (WebRTC) nella rete dell'host, come componente aggiuntivo docker-compose.pbx.yml; dalla 1.1.58 lo chiede l'installer (centralino). In passato c'era anche piper (annunci con voce neurale, solo fino alla 1.1.50) |
facoltativi (dalla 1.1.42): translate, translate-models | traduzione nell'inbox sul tuo server (LibreTranslate, rete interna senza internet) e il servizio una tantum che scarica i modelli linguistici: vedi sotto |
Aggiornamenti
Le nuove versioni arrivano come immagini da Docker Hub. Un banner nell'app segnala le nuove versioni (controllo aggiornamenti su crm.the-y.at).
- Automatico (dalla 1.1.53): le nuove installazioni si aggiornano di notte (03:30 ora del server, più un ritardo casuale fino a 45 minuti) con
update.sh: scarica la nuova versione → backup → riavvia app e worker → controllo (healthy + nuova versione) → se qualcosa va storto, torna a girare in automatico la versione precedente. Log:update.log. “Update now” nell'app avvia lo stesso processo. Le installazioni esistenti con Watchtower passano una volta al nuovo sistema (circa 5 minuti): Passare da Watchtower a update.sh. Per restare su una versione:CRM_TAGin.env. - Solo installazioni precedenti alla 1.1.53 (Watchtower): il servizio
watchtowerscarica ogni notte le nuove immagini:latestperapp/workere le riavvia, senza un backup prima. Ti consigliamo di passare al nuovo sistema. - A mano (in qualsiasi momento): nella cartella di installazione esegui
bash update.sh(con backup e controllo; una simulazione che non cambia nulla:bash update.sh --probe). Senzaupdate.sh:
cd ~/the-y-crm docker compose pull app worker docker compose up -d app worker
migrate prima di start): nessun passaggio a parte. Aggiornamento alla 1.1.53: al primo avvio l'app crea un indice di ricerca per i messaggi; con moltissimi messaggi (oltre 1 milione) salta questo passaggio, e il comando per farlo in seguito è nel log (docker compose logs app). In self-hosting non si può cambiare l'indirizzo dell'account: usi il tuo dominio.Disattivare gli aggiornamenti automatici: bash update.sh --zeitplan-aus (poi solo a mano con bash update.sh).
Passare da Watchtower a update.sh (installazioni precedenti alla 1.1.53)
Nulla cambia in automatico: Watchtower continua a girare finché non fai questo (circa 5 minuti, nella cartella di installazione, ad es. ~/the-y-crm; descritto anche in SELF-HOSTING.md, in tedesco):
- Scarica
update.sh(e, se vuoi,schluessel.sh) da the-y.at nella cartella di installazione:cd ~/the-y-crm curl -fsSL https://the-y.at/update.sh -o update.sh curl -fsSL https://the-y.at/schluessel.sh -o schluessel.sh # optional - Simulazione:
bash update.sh --probe; alla fine deve comparire “ERGEBNIS: bereit” (risultato: pronto). Se alla voce “Sicherung vorher” (prima il backup) c'è kein Sicherungs-Dienst (nessun servizio di backup) anche se hai impostato i backup giornalieri (installazioni precedenti alla 1.1.52), aggiungi la rigaCOMPOSE_FILE=docker-compose.yml:docker-compose.backup.ymla.enve ripeti la simulazione, altrimenti lo script aggiorna senza backup. Gli script di backup attuali si scaricano allo stesso modo (curl -fsSLO https://the-y.at/backup.sh, così comerestore.sh,restore-files.sherestore-test.sh; il filedocker-compose.backup.ymlconcurl -fsSL https://the-y.at/compose-backup.yml -o docker-compose.backup.yml); cosa fare poi lo trovi inSELF-HOSTING.md, sezione “Wiederherstellen” (ripristino). - Ferma e rimuovi Watchtower:
docker compose stop watchtower && docker compose rm -f watchtower, poi cancella l'intero bloccowatchtower:indocker-compose.yml(fino al servizio successivo o avolumes:). - Cancella le righe
WATCHTOWER_HTTP_API_TOKEN=…eWATCHTOWER_PERIODIC=…da.env(non servono più). Per il pulsante “Update now”,appha bisogno della riga./update-signal:/they-updatesottovolumes(le installazioni dalla 1.1.52 ce l'hanno); altrimenti aggiungila ed eseguimkdir -p update-signal:app: # … existing entries stay … volumes: - ./update-signal:/they-updatePoidocker compose up -d app worker. - Imposta la pianificazione:
bash update.sh --zeitplan(da root un timer systemd, altrimenti una voce cron; in più un watcher per il pulsante “Update now”). - Verifica:
systemctl list-timers the-y-crm-update.timerocrontab -l, ed esegui una voltabash update.sh --probe.
Le etichette di Watchtower su app e worker possono restare: senza Watchtower non fanno nulla. Installato con docker-compose.self-host.yml: stessi passaggi; perché update.sh usi il file giusto, aggiungi a .env: COMPOSE_FILE=docker-compose.self-host.yml. Quella configurazione non ha un servizio di backup: lo script aggiorna quindi senza backup, perciò prima fai tu un backup (Backup e ripristino). Tornare a Watchtower: bash update.sh --zeitplan-aus, rimetti il blocco watchtower nel tuo file compose, ripristina le due righe .env, docker compose up -d.
Watchtower segnala “client version … is too old” (solo installazioni precedenti alla 1.1.53)
Le nuove versioni di Docker rifiutano la vecchia interfaccia che Watchtower usa di solito; gli aggiornamenti automatici smettono quindi di arrivare. Con install.sh la riga giusta c'è già, e dalla 1.1.48 anche in docker-compose.self-host.yml. Se hai installato in un altro modo, aggiungi la riga al servizio watchtower (se ha già environment:, solo la seconda riga) e riavvialo. Gli aggiornamenti automatici non sostituiscono il file compose.
watchtower:
# … existing entries stay …
environment:
DOCKER_API_VERSION: "1.44"
docker compose up -d watchtower
Traduzione (facoltativa, dalla 1.1.42)
Il pulsante “🌐 Translate” nell'inbox traduce sul tuo server: LibreTranslate nella rete Docker translate-internal, senza accesso a internet e senza porte verso l'esterno. Nessun testo va a un servizio esterno. Il servizio è un profilo Compose facoltativo perché richiede fino a 1,5 GB di RAM.
| Fabbisogno | Valore |
|---|---|
| RAM | a riposo ~0,1 GB, tedesco/inglese/turco a pieno carico fino a ~0,9 GB; limite fisso 1,5 GB (TRANSLATE_MEM). Ogni lingua in più +0,2–0,4 GB. |
| Disco | modelli linguistici una tantum ~0,6 GB (tedesco, inglese, turco), più ~0,6 GB per l'immagine |
| Internet | solo una volta per scaricare i modelli (servizio una tantum translate-models); il servizio in funzione non ha accesso a internet |
Attivarlo
Esegui questo nella cartella di installazione (ad es. ~/the-y-crm). Se hai installato con docker-compose.self-host.yml, aggiungi ogni volta -f docker-compose.self-host.yml dopo docker compose.
# 1) enable the profile (languages optional, default de,en,tr) echo 'COMPOSE_PROFILES=translate' >> .env # echo 'TRANSLATE_LANGS=de,en,tr' >> .env # 2) download the language models once (~0.6 GB, ~1 minute, needs internet) docker compose --profile translate-models run --rm translate-models # 3) start the service and reconnect app/worker docker compose up -d translate app worker
Verifica: Settings → AI → Translation mostra “Translation service is running · Languages: EN, DE, TR”, e “Test translation” lo prova. Senza il servizio, dalla 1.1.59 l'inbox nasconde i pulsanti “Translate” (niente attese, nessun servizio esterno) e la scheda nelle impostazioni mostra i passaggi. Lì puoi scegliere in alternativa la tua chiave IA o DeepL (le chiavi DeepL Free non vengono usate per WhatsApp, Messenger e Instagram).
Installazione precedente alla 1.1.42?
Gli aggiornamenti automatici (Watchtower, o update.sh dalla 1.1.53) sostituiscono solo le immagini, non il file compose. Al tuo file mancano quindi i servizi translate + translate-models, la rete translate-internal e TRANSLATE_URL per app/worker. L'app continua a funzionare normalmente (i pulsanti “Translate” sono allora nascosti). Per attivarlo, fai una copia del file, aggiungi i blocchi qui sotto (sono uguali in docker-compose.self-host.yml e nel file compose che l'installer scrive dalla 1.1.42) e poi esegui i tre passaggi sopra.
cp docker-compose.yml docker-compose.yml.bak-pre-translate
# a) for app AND worker: add one line under environment:, plus networks: at the level of environment: environment: # … your existing lines … TRANSLATE_URL: ${TRANSLATE_URL:-http://translate:5000} networks: [default, translate-internal] # b) two new services under services: (e.g. after minio) translate: image: libretranslate/libretranslate:v1.9.6@sha256:1de2d7056bb8ad607a412f4563d9abe324ff632b43b5be9428bcc8e213aebb32 profiles: ["translate"] environment: LT_LOAD_ONLY: ${TRANSLATE_LANGS:-de,en,tr} LT_THREADS: "1" LT_DISABLE_WEB_UI: "true" LT_DISABLE_FILES_TRANSLATION: "true" LT_CHAR_LIMIT: "5000" ARGOS_INTRA_THREADS: "2" volumes: ["translate-models:/home/libretranslate/.local"] networks: [translate-internal] mem_limit: ${TRANSLATE_MEM:-1536m} memswap_limit: ${TRANSLATE_MEM:-1536m} healthcheck: test: ["CMD", "./venv/bin/python", "scripts/healthcheck.py"] interval: 30s timeout: 15s retries: 3 start_period: 60s restart: unless-stopped translate-models: image: libretranslate/libretranslate:v1.9.6@sha256:1de2d7056bb8ad607a412f4563d9abe324ff632b43b5be9428bcc8e213aebb32 profiles: ["translate-models"] entrypoint: ["./venv/bin/python", "scripts/install_models.py", "--update", "--load_only_lang_codes", "${TRANSLATE_LANGS:-de,en,tr}"] volumes: ["translate-models:/home/libretranslate/.local"] networks: [default] restart: "no" # c) at the very bottom: add translate-models to volumes: and create the internal network volumes: { postgres-data: {}, redis-data: {}, minio-data: {}, translate-models: {} } # keep your existing entries (e.g. caddy-data) networks: { default: {}, translate-internal: { internal: true } }
Poi esegui docker compose config -q && echo OK: deve stampare “OK”. Più lingue: estendi TRANSLATE_LANGS (ad es. de,en,tr,ar), ripeti il passaggio 2 e aumenta TRANSLATE_MEM (+0,2–0,4 GB per lingua). Croato, bosniaco e serbo non sono disponibili in LibreTranslate: per queste lingue usa la tua chiave IA. MYMEMORY_EMAIL non viene più usato.
Backup e ripristino
Fai regolarmente il backup di tre cose: il database Postgres, il volume MinIO (file/media) e il tuo .env (contiene, tra l'altro, la chiave di cifratura: senza, i segreti cifrati sono persi!).
Backup
# 1) database dump cd ~/the-y-crm docker compose exec -T postgres pg_dump -U crm crm | gzip > db-$(date +%F).sql.gz # 2) MinIO volume (files/media) — check the name: docker volume ls | grep minio docker run --rm -v theycrm_minio-data:/data -v "$PWD":/backup alpine \ tar czf /backup/minio-$(date +%F).tgz -C /data . # 3) back up .env (contains APP_ENCRYPTION_KEY!) cp .env env-$(date +%F).bak
Conserva i tre file in un luogo separato (altro server/storage). Con install.sh non ti serve un cron: il servizio backup fa ogni giorno alle 03:00 UTC il backup di database e file, conserva 14 giorni e sempre gli ultimi 3, e avvisa al 90 % di disco occupato (tramite BACKUP_PING_URL, se impostato). Il .env salvalo comunque tu. Senza questo servizio: automatizza con cron.
Ripristino
# restore the DB gunzip -c db-YYYY-MM-DD.sql.gz | docker compose exec -T postgres psql -U crm crm # restore the MinIO volume (stop the stack first) docker run --rm -v theycrm_minio-data:/data -v "$PWD":/backup alpine \ sh -c "rm -rf /data/* && tar xzf /backup/minio-YYYY-MM-DD.tgz -C /data"
APP_ENCRYPTION_KEY (AES-256). Se cambi o perdi questa chiave, tutti i segreti esistenti diventano impossibili da decifrare. Impostala una volta, in modo fisso, e salvala (fa parte del backup del tuo .env).Chiave con passphrase accanto ai backup (facoltativa, dalla 1.1.53)
Oltre a conservarla a parte, puoi salvare la chiave di cifratura cifrata con una passphrase (una password lunga) accanto ai tuoi backup. Dopo una perdita totale bastano allora il backup dal tuo secondo luogo di archiviazione e la passphrase. Senza passphrase il file non vale nulla, per te e per chiunque metta le mani sui tuoi backup. La passphrase non viene mai salvata sul server (né in file, né nel log); viene chiesta solo nel terminale. Se la perdi, il file non serve più: vale di nuovo il .env conservato a parte. Se non lo configuri, resta tutto come prima.
Le nuove installazioni (dalla 1.1.53) hanno schluessel.sh nella cartella di installazione; quelle più vecchie lo scaricano una volta con curl -fsSL https://the-y.at/schluessel.sh -o schluessel.sh.
bash schluessel.sh --sichern # save: enter the passphrase twice (at least 12 characters) → backups/schluessel.enc bash schluessel.sh --pruefen # check, now and then: still know the passphrase? does the file match the key in .env?
- Il backup giornaliero (
backup.shdalla 1.1.53; installazioni più vecchie:curl -fsSLO https://the-y.at/backup.sh) copiaschluessel.encnel tuo secondo luogo di archiviazione (BACKUP_REMOTE): solo il file cifrato, mai la chiave in chiaro. - Hai cambiato la chiave (nuovo
APP_ENCRYPTION_KEY)? Esegui di nuovobash schluessel.sh --sichern. - Il ripristino (
restore.shdalla 1.1.53; installazioni più vecchie:curl -fsSLO https://the-y.at/restore.sh) controlla prima di cambiare qualcosa se la chiave in.envcorrisponde al file, altrimenti si ferma. - Nuovo server senza il vecchio
.env: eseguiinstall.sh, copia i backup,schluessel.enccompreso, in~/the-y-crm/backups/e avviabash schluessel.sh --zurueckholen(recupero): chiede la passphrase e scrive la vecchia chiave in.env(una copia del.envprecedente viene conservata). Poi ripristina il backup e avvia app e worker condocker compose up -d app worker(“up”, non “start”: così leggono la chiave ripristinata).
Variabili d'ambiente (riferimento)
I valori principali del tuo .env (modello: .env.self-host.example). Quelli critici in grassetto.
| Variabile | A cosa serve |
|---|---|
APP_ENCRYPTION_KEY | Chiave hex da 32 byte fissa (openssl rand -hex 32) per la cifratura dei campi. Non cambiarla mai. |
DATABASE_URL | connessione Postgres come superuser (migrazioni/script) |
APP_DATABASE_URL | connessione dell'app come utente non superuser crm_app (applica la row-level security = isolamento dei tenant) |
BASE_DOMAIN | il tuo dominio (ad es. crm.yourcompany.com), usato ad es. per il softphone (WSS) |
TENANT_MODE | self-host: single (un solo tenant, nessuna registrazione esterna) |
LICENSE_KEY | la tua chiave Founder/di licenza; verificata online (tolleranza offline di 14 giorni) |
CONTROL_PLANE_URL | endpoint di verifica della licenza (predefinito: crm.the-y.at) |
S3_ENDPOINT / S3_BUCKET | collegamento MinIO (minio:9000 / crm-media) |
MINIO_ROOT_USER / _PASSWORD | credenziali MinIO (da generare) |
REDIS_PASSWORD | facoltativa (dalla 1.1.60): password per Redis, solo lettere minuscole e cifre (ad es. openssl rand -hex 24). Le nuove installazioni con install.sh la ricevono in automatico. Per aggiungerla a una esistente: metti la riga in .env; nel file Compose imposta REDIS_URL: redis://${REDIS_PASSWORD:+:${REDIS_PASSWORD:-}@}redis:6379 per app e worker e command: redis-server ${REDIS_PASSWORD:+--requirepass ${REDIS_PASSWORD:-}} per redis, poi docker compose up -d. Senza valore Redis gira senza password come prima. |
PLATFORM_SMTP_* / PLATFORM_MAIL_FROM | invio email di sistema facoltativo (reset password/inviti) senza una tua casella |
CRM_IMAGE/_WORKER_IMAGE/CRM_TAG | immagini Docker Hub + tag (predefinito :latest) |
COMPOSE_PROFILES | translate attiva il servizio di traduzione facoltativo (dalla 1.1.42, traduzione) |
TRANSLATE_LANGS | lingue del tuo servizio di traduzione (predefinito de,en,tr) |
TRANSLATE_MEM | limite di memoria del servizio di traduzione (predefinito 1536m) |
TRANSLATE_URL | serve solo se il tuo LibreTranslate gira altrove (predefinito http://translate:5000). MYMEMORY_EMAIL non viene più usato dalla 1.1.42. |
BACKUP_HOUR | ora del backup giornaliero in UTC (predefinito 3) |
BACKUP_KEEP_DAYS | per quanti giorni si conservano i backup (predefinito 14); gli ultimi 3 restano sempre |
BACKUP_REMOTE | facoltativo: destinazione esterna come remote rclone (vuoto = solo locale) |
BACKUP_PING_URL | facoltativo: URL di monitoraggio (ad es. healthchecks.io), segnala successi ed errori |
UPDATE_MIN_FREE_MB | spazio libero su disco in MB che update.sh richiede prima di un aggiornamento (predefinito 3072) |
DEFAULT_LOCALE | facoltativo (dalla 1.1.59): lingua dell'interfaccia prima dell'accesso, de, en, tr o it (dalla 1.1.70). Se non è impostata vale la lingua del browser, altrimenti il tedesco. Dopo l'accesso vale la lingua scelta dalla persona. |
telefonia: AMI_SECRET, TURN_SECRET, PBX ecc. | solo con il centralino attivo. Se lo configura l'installer (dalla 1.1.58), genera da solo AMI_SECRET e TURN_SECRET e imposta PBX=1 |
Reverse proxy e TLS
Il pacchetto include Caddy con HTTPS automatico (Let's Encrypt): basta far puntare il tuo dominio al server via DNS. Se hai già nginx/Apache davanti, fai da proxy verso l'app (porta interna 3000) e termina lì il TLS. Assicurati che le connessioni WebSocket passino (softphone/tempo reale). Per il telefono nel browser inoltra anche /asterisk-ws (righe per Nginx e Apache).
Monitoraggio e stato di salute
L'endpoint /api/public/health restituisce {"ok":true} con HTTP 200 (healthy) oppure {"ok":false} con HTTP 503 (ad es. database non raggiungibile o in sola lettura): dalla 1.1.42 solo questo campo. Collegalo al tuo monitoraggio (uptime check) e valuta lo stato HTTP, non una parola nel corpo della risposta. La versione è su /api/public/version. Stato dei container con docker compose ps, log con docker compose logs -f app worker.
Licenza
Il LICENSE_KEY viene verificato periodicamente online presso il nostro server di controllo (control plane); in caso di interruzione vale una tolleranza offline di 14 giorni. Se la licenza non è valida o è scaduta, l'istanza passa con delicatezza in sola lettura (nessun blocco brusco, nessuna cancellazione di dati). Le funzioni sono identiche a quelle della versione in cloud.
Senza chiave l'istanza funziona completamente per 14 giorni dal primo avvio, poi resta in sola lettura finché non inserisci una chiave. Con una chiave gratuita valgono i limiti di Free; con una chiave Paid non ci sono limiti.
Risoluzione dei problemi
Dopo una reinstallazione, casella email/WhatsApp/telefonia sono “rotti”
Quasi sempre è cambiato il APP_ENCRYPTION_KEY (ad es. rigenerato), e così i segreti cifrati esistenti diventano illeggibili. Ripristina la chiave originale dal backup del tuo .env. Se è persa per sempre, i segreti esterni (token/password) vanno reinseriti.
Le email non partono (timeout)
Molti provider cloud bloccano le porte di posta in uscita come protezione antispam: di solito solo la porta 25, Hetzner Cloud anche la 465, DigitalOcean anche 465 e 587 (secondo i provider, aggiornato al 12 nov 2026). La porta 587 con autenticazione quindi funziona quasi ovunque. Se è bloccata: falla sbloccare dal provider (ticket di assistenza) o invia le email tramite un'API HTTP. Dettagli e fonti: requisiti del server §6.
L'istanza è in sola lettura
La verifica della licenza non è riuscita (chiave non valida/scaduta, o nessuna verifica online riuscita da oltre 14 giorni). Controlla LICENSE_KEY e la raggiungibilità di CONTROL_PLANE_URL.
Un container non parte
docker compose logs app mostra la causa. Le più comuni: credenziali DB sbagliate, un APP_ENCRYPTION_KEY mancante o una porta occupata. Dopo modifiche al .env, docker compose up -d --force-recreate app worker.
