Di quanto server ha bisogno BookStack?

Di pochissimo. BookStack è un'applicazione PHP con un database MariaDB; un team di qualche decina di persone gira comodamente con 1 vCPU e 2 GB di RAM. Il disco serve soprattutto per le immagini e gli allegati caricati.

Quali sono le credenziali predefinite?

admin@admin.com con la password 'password'. Accedi e cambia entrambe subito, prima di condividere l'URL con chiunque.

Può usare il login aziendale?

Sì. BookStack supporta LDAP, SAML2 e OpenID Connect, così tutti accedono con il provider di identità che usate già.

Serve un IP dedicato?

Per un team sì. I colleghi lo aprono nel browser via HTTPS, e questo richiede la porta 443 in entrata sul tuo IP. Per un quaderno personale basta anche un tunnel SSH su un piano NAT.

Come faccio il backup?

Fai il dump del database e copia la cartella dei caricamenti, che sta nel volume di configurazione montato. La nostra guida a restic automatizza entrambe le cose in snapshot cifrati fuori sede.

VPS per BookStack: una wiki di team self-hosted

Esegui BookStack su un VPS come wiki di documentazione del team: setup Docker con MariaDB, HTTPS sul tuo dominio, primo accesso, backup e requisiti reali.

La documentazione di un team di solito muore in uno di due modi: dispersa in thread di chat che nessuno riesce a cercare, o sepolta in una wiki così scomoda che nessuno la aggiorna. BookStack è quella rara wiki self-hosted che le persone usano davvero. I contenuti stanno su scaffali, in libri, capitoli e pagine: una struttura che tutti capiscono senza formazione. E il server che richiede è quasi niente.

Perché BookStack

Struttura evidente. Libri e capitoli invece di un mucchio piatto di pagine.
Un editor che non spaventa nessuno. WYSIWYG di default, Markdown per chi lo preferisce.
Permessi veri. Ruoli per scaffale, libro o pagina: i documenti HR restano lontani dai collaboratori esterni.
Login aziendale. LDAP, SAML2 e OpenID Connect sono integrati.
I tuoi dati. Tutto sta in un database MariaDB e in una cartella sul tuo server.

Non è lo strumento giusto per tutto. La documentazione per sviluppatori che deve cambiare insieme al codice va nel repository, non in una wiki.

Cosa serve

BookStack è leggero. Per la maggior parte dei team, Micro-IP — 1 vCPU, 2 GB, $10 al mese — è più che sufficiente. L'IP dedicato è ciò che permette ai colleghi di raggiungerlo via HTTPS sul tuo dominio. Il disco cresce con screenshot e PDF caricati, non con il numero di pagine.

Installazione con Docker Compose

Useremo le diffusissime immagini di LinuxServer.io. Prima genera una chiave dell'applicazione:

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

Copia il valore base64:... che stampa. Poi crea docker-compose.yml:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://wiki.example.com
      - APP_KEY=base64:paste-your-key-here
      - DB_HOST=db
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=change-me
    volumes:
      - ./bookstack:/config
    ports:
      - 127.0.0.1:6875:80
    depends_on:
      - db
    restart: unless-stopped
  db:
    image: lscr.io/linuxserver/mariadb:latest
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=change-me-too
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=change-me
    volumes:
      - ./db:/config
    restart: unless-stopped

docker compose up -d
docker compose logs -f bookstack

APP_URL deve corrispondere all'indirizzo che userà la gente, https:// compreso. Se sbagli, immagini e link si rompono in modi strani. Altro su Compose nella nostra guida al deploy di uno stack.

HTTPS e primo accesso

Punta un sottodominio al server (come), metti nginx davanti a 127.0.0.1:6875 e aggiungi un certificato con certbot — la guida al reverse proxy ti accompagna passo passo.

Poi accedi con l'account predefinito: admin@admin.com / password. Cambia subito email e password, prima di condividere il link. Tutti gli altri ricevono un account proprio o accedono tramite il vostro provider di identità.

Backup

Due cose da proteggere: il database e i caricamenti in ./bookstack. Un job notturno come questo copre il database:

docker compose exec -T db mysqldump -u bookstack -pchange-me bookstack > /var/backups/bookstack.sql

Poi fai il backup fuori sede di /var/backups e della cartella compose — è esattamente ciò che fa la nostra guida a restic. I Managed Backups aggiungono sopra punti di ripristino giornalieri dell'intero server.

Manutenzione

Aggiornare è docker compose pull && docker compose up -d. BookStack esegue le migrazioni del database all'avvio. Leggi le note di rilascio prima delle versioni principali; sono brevi e chiare.

Se il team vuole anche un posto per ticket e codice, un server Git self-hosted sta benissimo accanto, sullo stesso tipo di piano.