Per gli amministratori
← Tutti gli argomenti

Installazione passo passo

La guida completa: scaricare e verificare il pacchetto, ./draften install, HTTPS, la licenza, la posta e la protezione del server.

L’intera procedura da un server vuoto a un funzionamento protetto: download del pacchetto, installazione, HTTPS, primo accesso, configurazione e protezione del server. Che cosa deve avere il server è nell’articolo Ambiente supportato; di che cosa è fatta un’installazione lo descrive Installare sul tuo server.

Prima di iniziare

Prepara:

Passo 1: prepara il server

Installa Docker Engine con il plugin compose. Su Ubuntu dal repository ufficiale di Docker:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Su altre distribuzioni segui https://docs.docker.com/engine/install/. Il pacchetto docker.io dei repository della distribuzione è spesso vecchio e non ha il plugin compose.

Verifica le versioni – Docker deve essere 24 o più recente e docker compose deve rispondere:

docker version --format '{{.Server.Version}}'
docker compose version

Passo 2: scarica il pacchetto

Il pacchetto si scarica da download.draften.ai con la chiave che si trova nel file di licenza. Questi comandi estraggono la chiave dalla licenza ed elencano le release disponibili:

KEY=$(sed -n 's/.*"payload":"\([^"]*\)".*/\1/p' licence-<numero>.json | tr '_-' '/+' | awk '{ while (length($0) % 4) $0 = $0 "="; print }' | base64 -d | sed -n 's/.*"key": *"\([^"]*\)".*/\1/p')
curl -fsS -H "Authorization: Bearer $KEY" https://download.draften.ai/v1/latest.json | sed -n 's/.*"payload":"\([^"]*\)".*/\1/p' | tr '_-' '/+' | awk '{ while (length($0) % 4) $0 = $0 "="; print }' | base64 -d

L’elenco mostra le release degli ultimi sei mesi – per ognuna versione, data, note, dimensione e checksum sha256 – e sotto latest la più recente che non è stata ritirata. Scarica quella versione:

curl -fS -H "Authorization: Bearer $KEY" -o draften-<versione>.tar https://download.draften.ai/v1/bundles/draften-<versione>.tar

Il pacchetto pesa circa 500 MB. Se il gateway risponde con l’errore 403, la licenza è sconosciuta, revocata o scaduta – il messaggio dice perché.

Server senza internet: scarica il pacchetto su un’altra macchina con gli stessi comandi e trasferiscilo sul server (per esempio con scp). In questo caso possiamo mandarti il checksum insieme al pacchetto.

Passo 3: verifica il pacchetto

Calcola il checksum e confrontalo con il valore sha256 di quella versione nell’elenco del passo 2:

sha256sum draften-<versione>.tar

Se i checksum non coincidono, non installare il pacchetto e contattaci. Questa è l’unica verifica manuale: ogni aggiornamento successivo l’installazione lo verifica da sola con le nostre chiavi.

Passo 4: scompatta il pacchetto ed esegui l’installer

Scegli la cartella in cui vivrà l’installazione, scompatta lì il pacchetto ed esegui l’installer:

sudo mkdir /srv/draften
sudo tar -xf draften-<versione>.tar -C /srv/draften
cd /srv/draften
sudo ./draften install

L’installer prima carica le immagini (un minuto o due) e verifica la firma e il contenuto del pacchetto. Se la verifica fallisce (“this bundle does not check out”), il pacchetto è danneggiato – scaricalo di nuovo.

Passo 5: rispondi alle domande dell’installer

L’installer fa le domande in inglese:

DomandaChe cosa inserire
Where will people open draften (the full address)l’indirizzo compreso https://, per esempio https://draften.firma.cz. Deve essere l’indirizzo che le persone usano davvero – da esso si costruiscono anche gli indirizzi di ritorno dell’accesso con Microsoft e Google
The organisation's nameil nome della tua organizzazione
Its short nameun nome breve: lettere minuscole, cifre e trattini. Lo propone a partire dal nome dell’organizzazione
The first administrator's e-maill’email del primo amministratore. Diventa proprietario dell’organizzazione e operatore dell’intera installazione
Their nameil suo nome
Their languagecs, en, de, fr, es, it, pt o pl (predefinito en)
Run the updateryes o no (predefinito yes). L’updater permette di aggiornare, cambiare il numero di processi, cambiare la chiave di cifratura e fare backup dall’interfaccia web. Ha accesso a Docker, cioè diritti di root sul server. Senza, tutto funziona dalla riga di comando
HTTPS certificate file (PEM)il percorso del certificato, se l’HTTPS deve terminare direttamente in draften; altrimenti lascia vuoto
Its private key fileil percorso della chiave del certificato

Con un certificato l’indirizzo deve iniziare con https://. Ogni risposta si può dare anche direttamente nel comando, così puoi automatizzare l’installazione con uno script; le opzioni le elenca ./draften help:

sudo ./draften install --url https://draften.firma.cz --org "Firma S.r.l." \
  --admin-email jan@firma.cz --admin-name "Jan Novák" --locale en --updater yes

Passo 6: che cosa fa l’installer

  1. Scrive le impostazioni e i segreti nel file .env – leggibile solo dal proprietario. Le password del database, la chiave di cifratura MASTER_KEY e i segreti delle sessioni li genera casualmente e non li stampa da nessuna parte.
  2. Crea le cartelle data/, backups/ e la prima organizzazione con l’amministratore.
  3. Avvia draften e verifica che risponda.
  4. Alla fine stampa l’indirizzo e il link per impostare la password del primo amministratore, e ricorda di salvare una copia di .env.

Se il primo avvio fallisce (“the first start failed”), guarda docker compose ps e docker compose logs. Se il link non viene stampato, lo trovi con il comando docker compose logs worker | grep set-password – il worker lo stampa a ogni avvio finché la password non esiste.

Salva subito una copia di .env fuori dal server – almeno il valore di MASTER_KEY. Con questa chiave sono cifrati l’accesso alle caselle, le chiavi dei modelli e le password per l’invio della posta. Senza di essa nessuno può leggerli, nemmeno da un backup – e noi non la abbiamo.

Passo 7: pubblica draften tramite HTTPS

A seconda di dove termina l’HTTPS, scegli una variante. Fai puntare il record DNS del tuo indirizzo al server (o al proxy).

HTTPS direttamente in draften

Se hai dato un certificato all’installer, draften ascolta sulla porta 443 e dalla porta 80 reindirizza all’HTTPS. Bastano il DNS e le porte 80 e 443 aperte. Il certificato si può aggiungere anche in seguito, e con lo stesso comando lo sostituisci dopo il rinnovo senza perdere nemmeno una richiesta:

sudo ./draften certificate cert.pem key.pem --url https://draften.firma.cz

Il rinnovo del certificato (per esempio con un client ACME) te lo procuri tu; dopo ogni rinnovo esegui questo comando.

Il tuo reverse proxy

Senza certificato draften ascolta solo su 127.0.0.1:8085. Un proxy sulla stessa macchina inoltra le richieste a questo indirizzo e passa le intestazioni Host e X-Forwarded-Proto. Per esempio per Caddy (il certificato se lo procura da solo):

draften.firma.cz {
    reverse_proxy 127.0.0.1:8085
}

o per nginx:

server {
    listen 443 ssl;
    server_name draften.firma.cz;
    ssl_certificate     /etc/ssl/draften/fullchain.pem;
    ssl_certificate_key /etc/ssl/draften/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8085;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Quando il proxy gira su un’altra macchina, imposta in .env WEB_BIND=0.0.0.0:8085, esegui sudo docker compose up -d e rendi la porta 8085 accessibile solo al proxy (vedi il passo 13).

Cloudflare Tunnel

Non serve nessuna porta aperta. In Cloudflare Zero Trust crea un tunnel e copia il suo token. In .env inserisci CLOUDFLARE_TUNNEL_TOKEN=<token>, aggiungi tunnel a COMPOSE_PROFILES (per esempio COMPOSE_PROFILES=updater,tunnel) ed esegui:

sudo docker compose up -d

Poi in Cloudflare aggiungi al tunnel un indirizzo pubblico (Public hostname) che porta a http://127.0.0.1:8085. Lascia WEB_BIND su 127.0.0.1:8085. L’immagine cloudflared Docker la scarica da Docker Hub – nel pacchetto non c’è.

Passo 8: imposta la password e accedi

Apri il link che l’installer ha stampato, imposta la password e hai già effettuato l’accesso. Il link si può usare una sola volta ed è valido per 7 giorni. Come appare la pagina per impostare la password lo mostra la guida Accedere.

Non copiare il link da nessuna parte e non inoltrarlo – chi lo ha imposta la password dell’amministratore.

Passo 9: carica la licenza

Nell’interfaccia apri Installazione → Installazione, in fondo nel riquadro Licenza scegli il file e caricalo. Finché l’installazione non ha una licenza, gli assistenti non elaborano posta e non si possono creare caselle né assistenti. Con la licenza l’updater controlla da solo le nuove release. Di più nell’articolo La licenza.

Passo 10: imposta le chiavi predefinite e l’invio della posta

Nella stessa pagina Installazione:

Passo 11: collega la posta e le persone

  1. Decidi come l’assistente accederà alla posta e preparalo presso Microsoft o Google: Microsoft 365, Google Workspace, un’altra casella tramite IMAP.
  2. Chi deve accedere con l’account Microsoft o Google, impostalo in Come accedono i membri.
  3. Aggiungi e collega una casella.
  4. Configura un assistente con la procedura guidata.
  5. Invita altre persone – Persone e ruoli.

Passo 12: verifica che tutto funzioni

sudo ./draften status

stampa la versione, lo stato di salute del web e dei worker, lo stato dell’HTTPS e dei backup. Nell’interfaccia la pagina Gestione mostra se i worker si fanno vivi – vedi Gestione e capacità. Quando qualcosa non va, aiuta Risoluzione dei problemi; il file per il nostro supporto lo crea sudo ./draften diagnose.

Passo 13: proteggi il server

Chi ha accesso al server ha accesso a tutto: alla posta nei messaggi, a .env con la chiave e ai backup. Proteggi quindi il server come un server di posta.

Firewall. Dall’esterno lascia passare solo ciò che serve:

Docker aggira le regole di UFW (e di firewalld) per le porte che pubblica. ufw deny 8085 non chiude una porta che Docker ha aperto su 0.0.0.0. Lascia quindi WEB_BIND su 127.0.0.1:8085 dove possibile; altrimenti limita l’accesso con un firewall davanti al server o con regole nella catena DOCKER-USER.

Le connessioni in uscita basta consentirle verso gli indirizzi dell’Ambiente supportato.

SSH. Accesso solo con chiave (PasswordAuthentication no), senza accesso diretto di root (PermitRootLogin no), amministratori con account propri e sudo.

Chi può usare Docker. Far parte del gruppo docker significa avere diritti di root. Dallo solo agli amministratori del server.

Aggiornamenti del sistema. Attiva gli aggiornamenti di sicurezza automatici (su Ubuntu unattended-upgrades) e aggiorna Docker insieme al sistema. Gli aggiornamenti di draften li gestisce l’updater – vedi Aggiornare con l’updater.

Updater. Ha accesso a Docker, cioè diritti di root. Se non ti serve, disattivalo: in .env togli updater da COMPOSE_PROFILES e nella cartella dell’installazione esegui sudo docker compose rm -sf updater. Aggiornamenti e backup li fai allora dalla riga di comando.

File dell’installazione. .env è leggibile solo dal proprietario, e così anche la cartella backups/ – lascialo così. Non condividere la cartella dell’installazione.

Backup fuori dal server. draften fa ogni giorno il backup del database in backups/ sullo stesso disco. Imposta la copia di backups/ e di .env altrove, cifrata – i dump contengono la posta. Dettagli: Backup e ripristino.

Chiave di cifratura. Quando se ne va qualcuno che conosceva .env, sostituisci MASTER_KEY (sudo ./draften rotate-key, o in Installazione) e salva la nuova copia di .env fuori dal server.

Prossimi passi

Versione solo testo