Come configurare HTTPS e un certificato SSL per ONLYOFFICE Docker

Per proteggere ONLYOFFICE Docs con HTTPS in Docker, utilizza un certificato che corrisponda al nome host pubblico, rendilo disponibile all'interno del container e pubblica la porta HTTPS del container. HTTPS è la connessione web crittografata; un certificato TLS aiuta i browser a verificare di aver raggiunto il server previsto. Questa guida utilizza un certificato e una chiave privata già ottenuti da un'autorità di certificazione (CA) attendibile. Se utilizzi un proxy inverso, segui l'opzione separata riportata di seguito, poiché il proxy potrebbe gestire HTTPS al posto di HTTPS.

Quale configurazione HTTPS è più adatta alla tua implementazione?

ONLYOFFICE Docs può servire HTTPS direttamente dal suo container Docker, oppure un reverse proxy come NGINX o Traefik può accettare HTTPS e inoltrare le richieste a Docs. Il TLS diretto è una scelta semplice per un server autonomo le cui porte pubbliche 80 e 443 sono disponibili. Un reverse proxy è spesso più semplice quando un altro servizio web possiede già tali porte o quando più siti condividono un unico server. Evita di configurare entrambi i livelli alla cieca: decidi quale componente termina il TLS e documenta se la connessione dal proxy al container è HTTP o HTTPS.

Questa procedura guidata configura HTTPS diretto con un certificato emesso da un'autorità di certificazione (CA). ONLYOFFICE documenta anche un'opzione automatica Let's Encrypt utilizzando LETS_ENCRYPT_DOMAINe LETS_ENCRYPT_MAIL; richiede che le porte 80 e 443 siano raggiungibili e non già occupate da un proxy. Un certificato autofirmato è utile per una rete di test privata, ma i browser pubblici e i servizi di archiviazione connessi non lo considereranno automaticamente attendibile.

Cosa bisogna preparare per prima cosa?

• Un host Linux con Docker Engine e il plugin Docker Compose installati.
• Un record DNS A per il nome host, ad esempio docs.example.com, che punta all'indirizzo IPv4 pubblico dell'host. Aggiungere un record AAAA solo se IPv6 è configurato e raggiungibile.
• Regole del firewall in entrata e del firewall cloud che consentono il protocollo TCP 443. Se si richiedono o si rinnovano certificati con convalida HTTP, potrebbe essere richiesto anche il protocollo TCP 80.
• Una catena di certificati per l'hostname specifico e la relativa chiave privata. Le autorità di certificazione solitamente forniscono un file completo della catena di certificati e un file della chiave privata.
• Una directory host persistente per il volume di dati ONLYOFFICE e un segreto JWT sicuro. JWT (JSON Web Token) è un segreto condiviso utilizzato per autenticare le richieste tra Docs e un'applicazione di integrazione.

Passaggio 1: Posizionare il certificato e la chiave privata sull'host

In questo esempio, l'host mantiene i dati persistenti in /srv/onlyoffice/data. Sostituisci il nome host e i percorsi di esempio con i tuoi. Memorizza l'intera catena del certificato come tls.crte la chiave privata corrispondente come tls.keyin una certssottocartella:

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

Assicurati che la chiave privata sia leggibile solo dall'account o dal servizio che ne ha bisogno. Non incollarla in un file Compose, in una segnalazione di bug o in un repository pubblico. Se Docker non riesce a leggere la chiave a causa di problemi di proprietà o di autorizzazioni, limita l'accesso solo all'ambiente di runtime del container, anziché rendere la chiave leggibile da tutti.

Prima di avviare il servizio, verifica le date e i nomi host del certificato:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

L'elenco dei nomi alternativi del soggetto (SAN) deve includere il nome host esatto che gli utenti visiteranno. È possibile confrontare le chiavi pubbliche derivate dal certificato e dalla chiave privata; i due hash devono corrispondere:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

Passaggio 2: Configurare il servizio Docker Compose

La documentazione Docker di ONLYOFFICE posiziona i certificati in /var/www/onlyoffice/Data/certs. L'elenco corrente delle variabili d'ambiente fornisce i nomi dei file dei certificati predefiniti come tls.crte tls.key, mentre le istruzioni di installazione di esempio utilizzano anche onlyoffice.crte onlyoffice.key. Impostare esplicitamente i percorsi evita di basarsi su una convenzione di denominazione dei file. La directory host viene montata tramite bind nella directory dei dati del container corrispondente e la porta 443 viene pubblicata come porta host 443.

Crea un compose.yamlfile simile a questo, sostituendo il valore JWT di esempio con un segreto generato per la tua installazione. Il tag immagine qui sotto è una versione di esempio; consulta l'elenco ufficiale delle immagini e utilizza la versione che intendi mantenere.

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

Genera un segreto sicuro openssl rand -hex 32e inseriscilo nel file di ambiente o nella configurazione di Compose con le autorizzazioni di file appropriate. Se un'altra app si integra con Docs, configura tale app con lo stesso segreto JWT e l'indirizzo HTTPS pubblico. Se si tratta di un'installazione esistente, conserva i volumi, le reti, le altre variabili d'ambiente e le impostazioni di integrazione quando modifichi il file Compose esistente; non sostituire una definizione di servizio funzionante con questo esempio minimo.

Avvia o ricrea il servizio dalla directory contenente il file Compose:

docker compose up -d
docker compose ps
docker compose logs --tail=100 documentserver

Passaggio 3: Testare HTTPS e il certificato

Apri https://docs.example.comil browser sostituendo il nome host con il tuo. Verifica che il browser mostri una connessione sicura e non segnali un'incongruenza del nome, un certificato scaduto o un emittente non attendibile. Conferma che la pagina di benvenuto di ONLYOFFICE Docs si carichi correttamente. Quando Docs è connesso a Nextcloud, ownCloud o un'altra piattaforma, prova anche ad aprire e salvare un documento; il solo blocco del browser non è sufficiente a dimostrare il corretto funzionamento delle richieste di callback dell'integrazione o della configurazione JWT.

Da una shell, richiedi al server il suo certificato TLS e verifica la risposta HTTPS:

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

Questa -servernameopzione invia il nome host utilizzando Server Name Indication (SNI), che consente a un server di selezionare il certificato corretto quando più nomi host condividono lo stesso indirizzo. Le date del certificato, l'emittente e il SAN devono corrispondere al certificato installato. Verificare docker compose logsse il browser non riesce a connettersi o se il container si riavvia ripetutamente.

E se un proxy inverso gestisse già HTTPS?

Se NGINX, Traefik, Caddy o un gateway di hosting possiedono già le porte pubbliche 80 e 443, potrebbe essere preferibile installare il certificato pubblico su tale proxy. In questa topologia, pubblicare il container Docs solo su una rete Docker privata o associare la sua porta HTTP all'interfaccia di loopback, quindi configurare il proxy per inoltrare le richieste e il traffico WebSocket necessari. Impostare l'indirizzo ONLYOFFICE dell'applicazione di integrazione sull'URL pubblico https://. Seguire le istruzioni correnti del proxy e di ONLYOFFICE per le intestazioni inoltrate e il TLS upstream; non pubblicare la porta 443 del container sulla stessa porta host già utilizzata dal proxy.

Scegli questo schema quando un proxy instrada il traffico per più servizi. Utilizza la configurazione diretta del container descritta sopra quando Docs deve gestire l'endpoint HTTPS pubblico e le porte necessarie sono libere. Se il proxy si connette al container tramite HTTP, tale passaggio interno non è crittografato; mantienilo su una rete privata fidata o configura TLS a monte se i requisiti di sicurezza lo richiedono.

Problemi comuni e come risolverli

• Il browser segnala che il certificato non è valido. Verifica il nome host SAN, la data di scadenza del certificato, la catena completa e che il DNS punti all'host previsto. Un certificato per il dominio principale non copre automaticamente un sottodominio.
• Il container segnala un certificato o una chiave mancante. Verificare il percorso di origine dell'host, la destinazione del bind mount, i nomi esatti dei file e i due SSL_..._PATHvalori. La sintassi di Docker --mountrichiede che il percorso di origine esista; anche i bind mount di Compose devono puntare alla directory esistente prevista.
• La porta 443 è già occupata. Interrompere il servizio in conflitto, utilizzare un proxy inverso oppure scegliere una porta host pubblica diversa e assicurarsi che l'URL e il firewall la indichino. Se è presente un proxy, di solito dovrebbe essere il proprietario della porta pubblica 443.
• HTTPS funziona, ma la modifica del documento non riesce. Verificare l'URL di integrazione, il segreto JWT su entrambi i servizi, le regole di inoltro del proxy e se Documenti riesce a raggiungere la piattaforma di archiviazione. Eseguire un test con un ciclo effettivo di apertura e salvataggio.
• Il certificato viene rinnovato, ma il sito continua a utilizzare quello vecchio. Verifica che il rinnovo abbia aggiornato il file montato sull'host e che ONLYOFFICE lo abbia ricaricato. Se necessario, riavvia il servizio dopo il rinnovo, ad esempio con un hook di distribuzione di Certbot che viene eseguito docker compose restart documentserverdalla directory del progetto Compose. Prima di affidarti all'automazione, testa il rinnovo con l'opzione di simulazione di Certbot.

Mantieni il certificato aggiornato

La configurazione HTTPS non è completa finché non viene pianificato il rinnovo. Registra chi emette e rinnova il certificato, dove viene memorizzata la chiave privata, quale processo copia i file rinnovati nella directory montata e come il servizio li ricarica. Esegui il test di simulazione del client di rinnovo, monitora la scadenza del certificato e verifica l'endpoint pubblico dopo ogni rinnovo. Se utilizzi le variabili Let's Encrypt integrate in ONLYOFFICE anziché un certificato gestito dall'host, segui le istruzioni Docker correnti per tale metodo e verifica il comportamento di rinnovo per l'immagine e la distribuzione esatte che utilizzi.

Per riferimento, consultare la guida all'installazione di Docker e HTTPS di ONLYOFFICE Docs , la documentazione sul bind-mount di Docker , la documentazione di Docker Compose , i tag ufficiali delle immagini Docker di ONLYOFFICE e le istruzioni ufficiali di Certbot . I tag disponibili e i dettagli dell'interfaccia possono cambiare; verificarli durante la preparazione di una nuova implementazione.