Come fare self-hosting di Wiki.js nel 2026: configurazione del database, TLS e test di ripristino

La maggior parte delle note sull'installazione di Wiki.js si ferma al primo caricamento della pagina. È troppo presto: DB_HOST è localhost all'interno del container oppure mancano gli header del proxy TLS. Un test di produzione efficace è più esigente: completa la configurazione, crea e modifica una pagina, carica contenuti multimediali, cercali e controlla la cronologia delle versioni dopo un riavvio.

Il ruolo di Wiki.js è semplice: un wiki Markdown con versioning e un editor moderno. Il suo perimetro operativo include più del solo processo web, quindi dipendenza, stato persistente e route pubblica devono essere identificati esplicitamente prima che arrivino dati reali.

Definisci il perimetro di runtime di Wiki.js

La topologia minima responsabile di Wiki.js comprende un solo listener privato sulla porta 3000, una route di ingresso e un confine dello stato documentato. Il contratto di rete di Wiki.js richiede un database Postgres, MySQL, MariaDB, MSSQL o SQLite raggiungibile. Mantieni gli endpoint privati su DNS interno, consenti solo le chiamate in uscita necessarie e assegna a Wiki.js credenziali di servizio con ambito limitato.

Convalida la topologia chiedendo a un client pulito di completare la configurazione, creare e modificare una pagina, caricare contenuti multimediali, cercarli e controllare la cronologia delle versioni dopo un riavvio. Durante l'esecuzione, monitora il tempo di risposta del database, l'indicizzazione della ricerca, lo storage dei contenuti multimediali e la latenza del provider di autenticazione. Il risultato indica se il miglioramento successivo riguarda memoria, storage, rete o un worker separato, invece di incoraggiare un dimensionamento arbitrario del container.

Progetta il ripristino di Wiki.js prima del lancio

All'interno dell'immagine standard di Wiki.js non è previsto alcuno stato applicativo scrivibile. Conserva il database, gli eventuali upload locali e gli asset personalizzati, insieme al digest fissato e alla configurazione della route verificata, invece di eseguire il backup di un filesystem vuoto del container.

Crea Wiki.js da zero su un altro host e verifica che pagine, cronologia, utenti, gruppi, contenuti multimediali e navigazione vengano ripristinati e che una pagina nota rimanga ricercabile. Se aggiungi un database separato, un room server o un livello di autenticazione, assegna a ciascun componente un responsabile esplicito per il ripristino. La guida da Git alla produzione mostra come un artifact riproducibile sostituisca un backup del container.

Registra il comando di ricostruzione e il test con output noto insieme alla release. Un piano di ripristino stateless funziona riproducendo il comportamento a partire da input affidabili; non dovrebbe dipendere dalla copia di un container in esecuzione e non trasparente.

Scegli il confine di trust di Wiki.js

Una distribuzione sicura di Wiki.js inizia riducendo le autorizzazioni. Evita di lasciare esposta la schermata di configurazione dopo la creazione del primo amministratore; rimuovi invece l'accesso pubblico alla configurazione, limita l'amministrazione e assegna al database del wiki credenziali proprie.

Gestisci DB_PASS in base al suo ruolo in Wiki.js: mantieni i valori sensibili fuori da Git, documenta gli effetti della rotazione e non sostituire mai un esempio pubblico in produzione. Limita le route amministrative, usa DNS privato per le dipendenze e verifica ogni bind mount. Quando i log vengono inviati a un sistema centralizzato, filtra i segreti e i contenuti privati prima che lascino il server.

Cosa deve superare il test prima che arrivino dati reali in Wiki.js

Un gate di produzione per Wiki.js dovrebbe poter essere eseguito da qualcuno che non ha realizzato la distribuzione. Fornisci a questa persona la versione fissata, un account di test non sensibile e questa attività: completa la configurazione, crea e modifica una pagina, carica contenuti multimediali, cercali e controlla la cronologia delle versioni dopo un riavvio. Se le istruzioni richiedono un accesso shell non documentato, il servizio non è ancora pronto dal punto di vista operativo.

Ripeti il gate dopo aver sostituito solo il container. Poi ripristina il database, gli eventuali upload locali e gli asset personalizzati in un'infrastruttura vuota e dimostra che pagine, cronologia, utenti, gruppi, contenuti multimediali e navigazione vengano ripristinati e che una pagina nota rimanga ricercabile. Misura il tempo di risposta del database, l'indicizzazione della ricerca, lo storage dei contenuti multimediali e la latenza del provider di autenticazione durante entrambe le esecuzioni riuscite; differenze inattese spesso rivelano una cache, un indice, un worker o un mount dei dati mancante.

Aggiungi un'esercitazione di gestione degli errori: nega temporaneamente all'identità di test l'accesso a un database Postgres, MySQL, MariaDB, MSSQL o SQLite raggiungibile. Wiki.js dovrebbe produrre un errore utile, preservare lo stato esistente e ripristinarsi quando la condizione valida ritorna. Salva i timestamp e le righe di log pertinenti, oscurando i segreti. Questa evidenza diventa il riferimento per la successiva modifica dell'immagine o della configurazione.

Avvia Wiki.js senza nascondere le parti variabili

Mantieni l'invocazione iniziale di Wiki.js sufficientemente riproducibile da poter essere verificata in una pull request.

docker run -d \
  --name wiki-js \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e DB_PASS=replace-with-a-long-random-value \
  -e DB_TYPE=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_PORT=5432 \
  -e DB_USER=wiki \
  -e DB_NAME=wiki \
  ghcr.io/requarks/wiki:2

Non fare affidamento su latest dopo l'arrivo dei dati reali. Acquisisci il digest funzionante, l'utente del container e la proprietà dei mount. Segui il log dell'applicazione durante un test completo — completa la configurazione, crea e modifica una pagina, carica contenuti multimediali, cercali e controlla la cronologia delle versioni dopo un riavvio — e annota eventuali migration prima di esporre la route al traffico di produzione.

Mantieni distinti gli URL interni ed esterni

Tratta l'URL esterno di Wiki.js come una configurazione che deve sopravvivere ai redeploy. Configura prima il site URL dopo aver instradato il servizio tramite HTTPS; poi instrada l'hostname verso la porta 3000 mantenendo invariati host e scheme originali.

La checklist per verificare la raggiungibilità della distribuzione può dimostrare che le richieste entrano nel container. Da quel momento, il problema noto — DB_HOST è localhost all'interno del container oppure mancano gli header del proxy TLS — deve essere analizzato in Wiki.js, nel suo stato o nel suo workload, non nell'automazione dei certificati.

Monitora il workload, non solo il container

Crea dashboard basate sul tempo di risposta del database, sull'indicizzazione della ricerca, sullo storage dei contenuti multimediali e sulla latenza del provider di autenticazione. Un grafico della CPU privo del contesto del workload non può spiegare perché Wiki.js sia lento. Aggiungi un controllo sintetico o pianificato che provi a completare la configurazione, creare e modificare una pagina, caricare contenuti multimediali, cercarli e controllare la cronologia delle versioni dopo un riavvio usando dati di test innocui.

Prima di un upgrade, considera questo rischio specifico dell'applicazione: le migration del database e i moduli di autenticazione di Wiki.js devono essere testati in staging prima di passare a un'altra linea di release. Ripristina un backup recente in una distribuzione isolata, esegui lì le migration e confronta il comportamento. Se DB_HOST è localhost all'interno del container oppure mancano gli header del proxy TLS, analizza il confine coinvolto — origine pubblica, storage o dipendenza — prima di modificare impostazioni non correlate.

Mantieni esplicito Wiki.js mentre Dockup gestisce il routing

Routing, certificati, sostituzione dei servizi e storage collegato sono obiettivi ragionevoli per l'automazione. Dockup li gestisce per Wiki.js e può predisporre il database gestito correlato oppure collegarsi a servizi sul server del cliente.

Non dovrebbe invece inventare la trust policy di Wiki.js. Dopo la distribuzione, configura il site URL dopo aver instradato il servizio tramite HTTPS, applica questo confine — rimuovi l'accesso pubblico alla configurazione, limita l'amministrazione e assegna al database del wiki credenziali proprie — e verifica il risultato di questo scenario: completa la configurazione, crea e modifica una pagina, carica contenuti multimediali, cercali e controlla la cronologia delle versioni dopo un riavvio. Il risultato è un'infrastruttura one-click con un test di accettazione specifico per l'applicazione.

Domande frequenti

Di cosa ha bisogno Wiki.js per una distribuzione di produzione?

Instrada il container Wiki.js sulla porta 3000 attraverso un'unica origine HTTPS. Il requisito di rete di supporto è un database Postgres, MySQL, MariaDB, MSSQL o SQLite raggiungibile. Non considerare Wiki.js pronto finché non puoi completare la configurazione, creare e modificare una pagina, caricare contenuti multimediali, cercarli e controllare la cronologia delle versioni dopo un riavvio.

Quali dati di Wiki.js devono rientrare in un backup?

L'immagine standard di Wiki.js non richiede alcun mount per i dati applicativi. Conserva la configurazione della distribuzione ed esegui il backup separato di ogni stato collegato; il ripristino è superato quando pagine, cronologia, utenti, gruppi, contenuti multimediali e navigazione vengono ripristinati e una pagina nota rimane ricercabile.

Wiki.js richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Wiki.js e mantieni la porta 3000 sulla route interna. Applica correttamente l'impostazione di Wiki.js: configura il site URL dopo aver instradato il servizio tramite HTTPS. Per Wiki.js, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento client sensibile all'origine.

Come deve essere testato un upgrade di Wiki.js?

Ripristina lo stato attuale di Wiki.js in una distribuzione isolata, applica la versione candidata e ripeti la transazione di accettazione. Presta particolare attenzione perché le migration del database e i moduli di autenticazione di Wiki.js devono essere testati in staging prima di passare a un'altra linea di release. Mantieni l'immagine precedente di Wiki.js finché non avrai compreso i limiti della migrazione dei dati e del rollback.