Guide > Self-hosting > Gestione

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.

Per chi: self-hosting (chiave a pagamento o gratuita) · Docker Compose · utili conoscenze di base di Linux · Aggiornato al 12 nov 2026 (versione 1.1.65)

Lo stack in breve

The-Y gira come stack Docker Compose. I servizi:

ServizioA cosa serve
appla web app (Next.js), in ascolto internamente sulla porta 3000
workerjob in background (recupero email, promemoria, pulizie periodiche, pianificatore delle automazioni)
postgresdatabase (tutti i dati dei tenant)
rediscoda dei job (BullMQ)
minioarchivio file/media (allegati, registrazioni), compatibile S3
caddyreverse proxy con HTTPS automatico
watchtowersolo 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, coturncentralino 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-modelstraduzione 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).

cd ~/the-y-crm
docker compose pull app worker
docker compose up -d app worker
Le migrazioni del database partono da sole all'avvio dell'app (il container esegue 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):

  1. 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
  2. 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 riga COMPOSE_FILE=docker-compose.yml:docker-compose.backup.yml a .env e 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ì come restore.sh, restore-files.sh e restore-test.sh; il file docker-compose.backup.yml con curl -fsSL https://the-y.at/compose-backup.yml -o docker-compose.backup.yml); cosa fare poi lo trovi in SELF-HOSTING.md, sezione “Wiederherstellen” (ripristino).
  3. Ferma e rimuovi Watchtower: docker compose stop watchtower && docker compose rm -f watchtower, poi cancella l'intero blocco watchtower: in docker-compose.yml (fino al servizio successivo o a volumes:).
  4. Cancella le righe WATCHTOWER_HTTP_API_TOKEN=… e WATCHTOWER_PERIODIC=… da .env (non servono più). Per il pulsante “Update now”, app ha bisogno della riga ./update-signal:/they-update sotto volumes (le installazioni dalla 1.1.52 ce l'hanno); altrimenti aggiungila ed esegui mkdir -p update-signal:
      app:
        # … existing entries stay …
        volumes:
          - ./update-signal:/they-update
    Poi docker compose up -d app worker.
  5. 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”).
  6. Verifica: systemctl list-timers the-y-crm-update.timer o crontab -l, ed esegui una volta bash 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.

FabbisognoValore
RAMa 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.
Discomodelli linguistici una tantum ~0,6 GB (tedesco, inglese, turco), più ~0,6 GB per l'immagine
Internetsolo 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"
Il prodotto ha anche un export/import snapshot per tenant (Settings → Data backup), comodo per le migrazioni e come backup a livello di applicazione. Lo snapshot non contiene file (allegati, ricevute, PDF delle fatture, registrazioni) né password, chiavi 2FA o chiavi webhook. Gli utenti ripristinati sono disattivati e reimpostano la password con “Forgot password?”. Piano, fatturazione e impostazioni di sicurezza non vengono ripresi. Il backup DB+MinIO qui sopra è il backup completo dell'infrastruttura.
⚠ La chiave di cifratura è fondamentale. I token di caselle email, SIP, API e canali sono salvati cifrati con 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?

Variabili d'ambiente (riferimento)

I valori principali del tuo .env (modello: .env.self-host.example). Quelli critici in grassetto.

VariabileA cosa serve
APP_ENCRYPTION_KEYChiave hex da 32 byte fissa (openssl rand -hex 32) per la cifratura dei campi. Non cambiarla mai.
DATABASE_URLconnessione Postgres come superuser (migrazioni/script)
APP_DATABASE_URLconnessione dell'app come utente non superuser crm_app (applica la row-level security = isolamento dei tenant)
BASE_DOMAINil tuo dominio (ad es. crm.yourcompany.com), usato ad es. per il softphone (WSS)
TENANT_MODEself-host: single (un solo tenant, nessuna registrazione esterna)
LICENSE_KEYla tua chiave Founder/di licenza; verificata online (tolleranza offline di 14 giorni)
CONTROL_PLANE_URLendpoint di verifica della licenza (predefinito: crm.the-y.at)
S3_ENDPOINT / S3_BUCKETcollegamento MinIO (minio:9000 / crm-media)
MINIO_ROOT_USER / _PASSWORDcredenziali MinIO (da generare)
REDIS_PASSWORDfacoltativa (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_FROMinvio email di sistema facoltativo (reset password/inviti) senza una tua casella
CRM_IMAGE/_WORKER_IMAGE/CRM_TAGimmagini Docker Hub + tag (predefinito :latest)
COMPOSE_PROFILEStranslate attiva il servizio di traduzione facoltativo (dalla 1.1.42, traduzione)
TRANSLATE_LANGSlingue del tuo servizio di traduzione (predefinito de,en,tr)
TRANSLATE_MEMlimite di memoria del servizio di traduzione (predefinito 1536m)
TRANSLATE_URLserve solo se il tuo LibreTranslate gira altrove (predefinito http://translate:5000). MYMEMORY_EMAIL non viene più usato dalla 1.1.42.
BACKUP_HOURora del backup giornaliero in UTC (predefinito 3)
BACKUP_KEEP_DAYSper quanti giorni si conservano i backup (predefinito 14); gli ultimi 3 restano sempre
BACKUP_REMOTEfacoltativo: destinazione esterna come remote rclone (vuoto = solo locale)
BACKUP_PING_URLfacoltativo: URL di monitoraggio (ad es. healthchecks.io), segnala successi ed errori
UPDATE_MIN_FREE_MBspazio libero su disco in MB che update.sh richiede prima di un aggiornamento (predefinito 3072)
DEFAULT_LOCALEfacoltativo (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.

Prossimi passi