VPS para BookStack: uma wiki de equipe auto-hospedada

A documentação de equipe costuma morrer de um de dois jeitos: espalhada em threads de chat que ninguém consegue pesquisar, ou enterrada numa wiki tão desajeitada que ninguém atualiza. O BookStack é aquela rara wiki auto-hospedada que as pessoas de fato usam. O conteúdo fica em estantes, livros, capítulos e páginas — uma estrutura que todo mundo entende sem treinamento. E ele quase não pede servidor.

Por que BookStack

• Estrutura óbvia. Livros e capítulos em vez de uma pilha plana de páginas.
• Edição que não assusta ninguém. Editor WYSIWYG por padrão, Markdown para quem prefere.
• Permissões de verdade. Papéis por estante, livro ou página — documentos de RH longe de terceirizados.
• Login da empresa. LDAP, SAML2 e OpenID Connect já vêm embutidos.
• Seus dados. Tudo fica num banco MariaDB e numa pasta no seu servidor.

Não é a ferramenta certa para tudo. Documentação de desenvolvimento que precisa mudar junto com o código pertence ao repositório, não a uma wiki.

Do que precisa

O BookStack é leve. Para a maioria das equipes, o Micro-IP — 1 vCPU, 2 GB, $10 por mês — é mais que suficiente. O IP dedicado é o que permite aos colegas acessar via HTTPS no seu domínio. O disco cresce com prints e PDFs enviados, não com o número de páginas.

Instalação com Docker Compose

Vamos usar as populares imagens da LinuxServer.io. Primeiro gere uma chave da aplicação:

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

Copie o valor base64:... que aparece. Depois crie o 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 precisa bater com o endereço que as pessoas vão usar, incluindo https://. Se errar, imagens e links quebram de jeitos estranhos. Mais sobre Compose no nosso guia de deploy de stack.

HTTPS e primeiro login

Aponte um subdomínio para o servidor (como), coloque o nginx na frente de 127.0.0.1:6875 e adicione um certificado com o certbot — o guia de proxy reverso mostra o passo a passo.

Depois entre com a conta padrão: admin@admin.com / password. Troque o e-mail e a senha na hora, antes de compartilhar o link. Os demais recebem conta própria ou entram pelo seu provedor de identidade.

Backups

Duas coisas a proteger: o banco de dados e os uploads dentro de ./bookstack. Uma tarefa noturna como esta cobre o banco:

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

Depois faça backup externo de /var/backups e da pasta do compose — é exatamente o que nosso guia de restic faz. Os Managed Backups somam por cima pontos de restauração diários do servidor inteiro.

Manutenção

Atualizar é docker compose pull && docker compose up -d. O BookStack roda as migrações do banco ao iniciar. Leia as notas de versão antes das versões principais; são curtas e claras.

Se sua equipe também quer um lugar para tickets e código, um servidor Git auto-hospedado fica ótimo ao lado, no mesmo tipo de plano.