Ospitare BookStack su un VPS gestito: la vostra documentazione a casa vostra

Che cosa fa BookStack

BookStack è una piattaforma di documentazione pensata per restare semplice: il suo README punta a una presa in mano immediata, con semplici nozioni di elaborazione testi. I vostri team vi scrivono le loro procedure, la loro documentazione e la loro base di conoscenza, in un browser, in italiano se lo desiderano.

• Quattro livelli di organizzazione: gli scaffali raggruppano dei libri, i libri contengono capitoli e pagine, i capitoli sono facoltativi, e il contenuto vive nelle pagine.
• Due editor: un editor visuale predefinito, e un editor Markdown con anteprima in diretta, a cui si aggiungono gli schemi diagrams.net.
• La ricerca: in un libro, o sull'insieme di libri, capitoli e pagine.
• I diritti: ruoli per tutto il sistema, e permessi propri di uno scaffale, di un libro, di un capitolo o di una pagina.
• Gli accessi: e-mail e password, OpenID Connect, SAML 2.0, LDAP, con un'autenticazione a due fattori tramite app o codici di emergenza, che si può imporre per ruolo.
• Il monitoraggio e gli scambi: la cronologia delle revisioni di ogni pagina, un'API REST e l'esportazione in HTML, PDF, testo, Markdown o ZIP portabile.

Il progetto assume le proprie scelte: il suo README precisa che BookStack non è concepito come una piattaforma estensibile verso altri usi, e resta fedele alla documentazione. Il suo rendering PDF passa da dompdf, senza altra installazione, con capacità limitate; il progetto documenta altri motori con EXPORT_PDF_COMMAND.

Che cosa consente la licenza MIT

BookStack è pubblicato con licenza MIT da Dan Brown e dai collaboratori del progetto. Autorizza qualsiasi uso, qualsiasi modifica e qualsiasi distribuzione, a una condizione: conservare la nota di copyright e il testo della licenza in ogni copia del software. Le FAQ del progetto precisano che questa attribuzione riguarda il codice che condividete: nulla vi obbliga a mostrare il nome o il logo di BookStack sulla vostra istanza.

Il progetto mantiene una sola versione, libera e gratuita: non propone un'edizione enterprise, e non ha un hosting ufficiale, né il progetto di aprirne uno. Vende invece piani di assistenza, che contribuiscono al suo finanziamento insieme alle donazioni e agli sponsor. BookStack si installa quindi sul vostro server, senza alcuna licenza da acquistare.

I requisiti di BookStack

Docker resta facoltativo. Il progetto non pubblica un'immagine ufficiale: le installazioni in container vengono da progetti comunitari, LinuxServer.io e solidnerd. Questa guida segue la via ufficiale, PHP e MySQL direttamente sul server, che non richiede nulla di più.

La documentazione esclude l'hosting PHP condiviso: BookStack richiede un server che amministrate voi. Non indica né la memoria né il processore necessari. Su un VPS gestito, descrivetici il vostro uso, il numero di persone e il volume di immagini e allegati, e vi raccomandiamo la taglia adatta.

L'installazione di BookStack

Il progetto propone due vie: uno script per Ubuntu, il più breve su un server nuovo, e un'installazione manuale per tutti gli altri casi.

Con lo script del progetto, su un Ubuntu appena installato

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

Questi script sono riservati a un sistema appena installato: possono sovrascrivere una configurazione web esistente. Lasciano inoltre da parte due temi, le impostazioni delle e-mail e la sicurezza del sistema, da prevedere a parte.

Lo script installa BookStack in /var/www/bookstack. Quello di Ubuntu 26.04 chiede il dominio e l'indirizzo dell'account amministratore, poi mostra alla fine una password generata a caso, assente dal suo log: annotatela. Con un altro script, prendete nota delle credenziali mostrate alla fine e cambiate qualsiasi accesso predefinito fin dal primo accesso.

A mano, su qualsiasi altra macchina

Cominciate dal database: un database e un utente limitato a quel database. Lo script del progetto procede così, con la password che preferite al posto di change-me:

sudo mysql -u root --execute="CREATE DATABASE bookstack;"
sudo mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'change-me';"
sudo mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"

Recuperate poi il ramo release, impostate i permessi che la documentazione indica per /var/www/bookstack, poi installate le dipendenze:

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Compilate il database e l'indirizzo in .env:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Puntate infine la radice web sulla cartella public: DocumentRoot su Apache, root su Nginx. Senza Apache, o quando i file .htaccess sono disattivati, aggiungete le regole di riscrittura degli indirizzi: il progetto pubblica degli esempi per Apache e per Nginx.

Un'installazione manuale si apre con l'account admin@admin.com e la password password. Cambiate l'indirizzo e la password fin dal primo accesso.

HTTPS e APP_URL

I visitatori arrivano sulle porte 80 e 443, con il nome di dominio del server. Create per questo nome dei record A e AAAA, poi richiedete il certificato: lo script di Ubuntu 26.04 configura Apache sulla sola porta 80, e la pagina di installazione lascia HTTPS a voi. Certbot installa il certificato Let's Encrypt, adatta Apache e rinnova il certificato in autonomia. Con Nginx, sostituite --apache con --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Portate poi l'indirizzo in HTTPS nel .env. APP_URL deve corrispondere esattamente all'indirizzo di visita, prefisso compreso: uno scarto si nota da stili assenti, icone enormi e menu rotti. Un indirizzo in https attiva da sé i cookie sicuri.

APP_URL=https://docs.example.com

Se esistono già delle pagine, i loro link conservano il vecchio indirizzo nel database. Salvate il database, poi lanciate il comando del progetto:

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

BookStack si serve dalla radice di un dominio o di un sottodominio, e la documentazione descrive anche un'installazione in una sottocartella, come example.com/bookstack. Se un reverse proxy si aggiunge davanti ad Apache, dichiarate il suo indirizzo in APP_PROXIES: senza di esso, il registro di audit e la limitazione della frequenza vedono l'indirizzo del proxy al posto di quello dei visitatori. La documentazione riserva APP_PROXIES="*" alla diagnostica.

Dove vivono i vostri dati

Mantenete nel tempo la stessa APP_KEY e salvatela. BookStack la usa per cifrare in particolare i segreti dell'autenticazione a due fattori: cambiarla può rompere queste funzioni, e dalla versione 26.09 l'applicazione restituisce un errore se manca.

Le immagini sono pubbliche per impostazione predefinita

Con l'archiviazione predefinita, il server web serve direttamente le immagini, il che è veloce, e chiunque ne conosca l'indirizzo può aprirle. Per una documentazione interna, la scelta si fa in STORAGE_TYPE:

Per i file pesanti, tre impostazioni vanno armonizzate: FILE_UPLOAD_SIZE_LIMIT nel .env, post_max_size e upload_max_filesize in php.ini, e client_max_body_size con Nginx, che vale 1 MB per impostazione predefinita.

Altre due impostazioni contano per una documentazione viva: ogni pagina conserva 100 revisioni per impostazione predefinita (REVISION_LIMIT), e il cestino conserva gli elementi eliminati per 30 giorni (RECYCLE_BIN_LIFETIME).

Le e-mail: SMTP e coda

BookStack invia e-mail per la conferma degli indirizzi, la password dimenticata, gli inviti e le notifiche. Da un VPS Simafri, l'invio passa da un relay SMTP autenticato, sulla porta 587: l'indirizzo di un account di posta che avete già, oppure Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Verificate il risultato in «Settings», «Maintenance», con l'azione «Send a Test Email», che mostra gli errori incontrati. Un errore durante un invito compare a schermo, mentre un errore di notifica resta nel log dell'applicazione.

Inviare in background

Per impostazione predefinita, BookStack invia e-mail e webhook durante la richiesta, il che può rallentare le pagine. Per passare in background, scrivete QUEUE_CONNECTION=database nel .env e fate girare un servizio, con l'esempio che la documentazione fornisce per un'installazione Ubuntu tramite script:

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Mettere in sicurezza la vostra istanza BookStack

La documentazione sulla sicurezza fornisce una lista da riprendere fin dall'installazione:

1. Cambiate l'indirizzo e la password del primo amministratore.
2. Verificate che il server web serva la sola cartella public, soprattutto se BookStack vive sotto /var/www.
3. Limitate l'utente del database al solo database di BookStack.
4. Compilate APP_URL, affinché gli indirizzi generati dal sistema non possano essere manipolati.
5. Rileggete le impostazioni di iscrizione e di accesso pubblico, poi i ruoli.

L'autenticazione a due fattori si impone poi per ruolo. Iscrivetevi anche alla mailing list di sicurezza del progetto, per ricevere i suoi avvisi. L'indirizzo /status serve a un monitoraggio: risponde 200 quando tutto va bene, e un codice di errore pari o superiore a 400 in caso contrario.

PHP conta quanto BookStack. Il progetto ha pubblicato il 21 ottobre 2026 un avviso su un aggiornamento critico di PHP, corretto nelle versioni 8.5.12, 8.4.27, 8.3.36 e 8.2.35. Ubuntu pubblica queste correzioni con i propri numeri di pacchetto, come 8.3.6-0ubuntu0.24.04.13 per Ubuntu 24.04.

Per i vostri contenuti, mantenete attivo il filtraggio predefinito e riservate il suo allentamento alle istanze in cui scrivono solo persone di fiducia. Se un account amministratore va perso, php artisan bookstack:create-admin ne crea un altro, e php artisan bookstack:reset-mfa toglie l'autenticazione a due fattori a un utente.

Backup e aggiornamenti

Un backup completo riunisce il database e i quattro percorsi di file propri della vostra istanza. Le esportazioni di contenuto servono ad altro: la documentazione precisa che non sostituiscono un backup.

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

La prima riga riguarda un'installazione tramite script, dove il root di MySQL si connette con sudo; altrove, scrivete mysqldump -u bookstack -p bookstack. Riponete questi due file a parte, preferibilmente su un'altra macchina. L'archivio contiene .env, quindi APP_KEY e le vostre password: trattatelo come un segreto.

Ripristinare

Su una macchina nuova, installate BookStack senza lanciare php artisan migrate, un passaggio da commentare nello script se lo usate, poi ripristinate il database e i file, conservando l'APP_KEY d'origine:

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

Se la versione installata è più recente del backup, lanciate poi php artisan migrate. Ripristinate i diritti di scrittura del server web sulle cartelle ripristinate. Se l'indirizzo è cambiato, correggete APP_URL e lanciate bookstack:update-url.

Aggiornare

Salvate il database e i file prima di ogni aggiornamento, poi, dalla cartella di BookStack:

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

Lo script per Ubuntu 26.04 installa BookStack senza Composer. La pagina degli aggiornamenti propone allora, in beta, ./bookstack-system-cli download-vendor al posto di composer install --no-dev. Questo stesso strumento sa salvare e ripristinare, ma il progetto non lo considera ancora pronto per la produzione: provatelo prima di fidarvene.

La documentazione mantiene un elenco di indicazioni proprie di ogni versione, da leggere per la versione desiderata. Alcuni esempi:

• Versione 26.09: APP_KEY diventa obbligatoria.
• Versione 26.05: la cartella storage/fonts deve restare scrivibile dal server web, altrimenti le esportazioni PDF possono fallire.
• Versione 26.03: provate l'invio delle e-mail dopo l'aggiornamento.
• Versione 25.11: grosse modifiche al database, la cui migrazione può richiedere diversi minuti su un'istanza grande.

Le falle si correggono in versioni di manutenzione, come la 26.09.3 dell'11 novembre 2026: le immagini e i disegni di una pagina in bozza o nel cestino restavano accessibili e modificabili, e la bozza personale di un redattore poteva diventare visibile ad altre persone.

Chi fa che cosa su un VPS gestito

Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; BookStack resta il vostro software, con le sue impostazioni e i suoi dati.

Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.