Alojar BookStack num VPS gerido: a sua documentação no seu servidor

O que faz o BookStack

O BookStack é uma plataforma de documentação pensada para se manter simples: o seu README visa uma adoção imediata, com simples noções de processamento de texto. As suas equipas escrevem aí os seus procedimentos, a sua documentação e a sua base de conhecimento, num navegador, em português, se assim o desejarem.

• Quatro níveis de arrumação: as prateleiras agrupam livros, os livros contêm capítulos e páginas, os capítulos são facultativos, e o conteúdo vive nas páginas.
• Dois editores: um editor visual por predefinição e um editor Markdown com pré-visualização em direto, aos quais se juntam os esquemas diagrams.net.
• A pesquisa: dentro de um livro, ou em todos os livros, capítulos e páginas.
• Os direitos: funções para todo o sistema e permissões próprias de uma prateleira, de um livro, de um capítulo ou de uma página.
• Os inícios de sessão: e-mail e palavra-passe, OpenID Connect, SAML 2.0, LDAP, com uma autenticação de dois fatores por aplicação ou por códigos de recurso, que se pode impor por função.
• O acompanhamento e as trocas: o histórico das revisões de cada página, uma API REST e a exportação em HTML, PDF, texto, Markdown ou ZIP portátil.

O projeto assume as suas escolhas: o seu README esclarece que o BookStack não foi concebido como uma plataforma extensível para outras utilizações, e continua fiel à documentação. O seu processamento de PDF passa pelo dompdf, sem instalação adicional, com capacidades limitadas; o projeto documenta outros motores com EXPORT_PDF_COMMAND.

O que permite a licença MIT

O BookStack é publicado sob a licença MIT por Dan Brown e pelos contribuidores do projeto. Autoriza qualquer utilização, qualquer modificação e qualquer distribuição, com uma condição: manter a menção de direitos de autor e o texto da licença em qualquer cópia do software. As FAQ do projeto esclarecem que esta atribuição diz respeito ao código que partilha: nada o obriga a mostrar o nome ou o logótipo do BookStack na sua instância.

O projeto mantém uma única versão, livre e gratuita: não propõe edição empresarial, e não tem alojamento oficial, nem projeto de abrir um. Vende, em contrapartida, planos de suporte, que contribuem para o seu financiamento com os donativos e os patrocínios. O BookStack instala-se, portanto, no seu servidor, sem licença para comprar.

Os pré-requisitos do BookStack

O Docker continua a ser facultativo. O projeto não publica imagem oficial: as instalações em contentor vêm de projetos comunitários, LinuxServer.io e solidnerd. Este guia segue o caminho oficial, PHP e MySQL diretamente no servidor, que não exige nada mais.

A documentação afasta o alojamento PHP partilhado: o BookStack exige um servidor que administre. Não quantifica nem a memória nem o processador necessários. Num VPS gerido, descreva-nos a sua utilização, o número de pessoas e o volume de imagens e de anexos, e recomendamos-lhe o tamanho adequado.

A instalação do BookStack

O projeto propõe dois caminhos: um script para Ubuntu, o mais curto num servidor novo, e uma instalação manual para todos os outros casos.

Com o script do projeto, num Ubuntu novo em folha

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

Estes scripts estão reservados a um sistema acabado de instalar: podem sobrescrever uma configuração web existente. Deixam também de lado dois assuntos, as definições de e-mail e a segurança do sistema, a prever à parte.

O script instala o BookStack em /var/www/bookstack. O do Ubuntu 26.04 pede o domínio e o endereço da conta de administrador e mostra no fim uma palavra-passe aleatória, ausente do seu registo: anote-a. Com outro script, anote os acessos mostrados no fim e mude qualquer acesso predefinido logo no primeiro início de sessão.

À mão, em qualquer outra máquina

Comece pela base de dados: uma base de dados e um utilizador limitado a essa base. O script do projeto procede assim, com a palavra-passe da sua escolha no lugar de 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;"

Obtenha depois a ramificação release, defina os direitos que a documentação dá para /var/www/bookstack e instale as dependências:

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

Preencha a base de dados e o endereço no .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

Aponte por fim a raiz web para a pasta public: DocumentRoot no Apache, root no Nginx. Sem Apache, ou quando os ficheiros .htaccess estão desativados, acrescente as regras de reescrita de endereços: o projeto publica exemplos para o Apache e para o Nginx.

Uma instalação manual abre-se com a conta admin@admin.com e a palavra-passe password. Mude o endereço e a palavra-passe logo no primeiro início de sessão.

HTTPS e APP_URL

Os visitantes chegam pelas portas 80 e 443, sob o nome de domínio do servidor. Crie para esse nome registos A e AAAA e peça depois o certificado: o script do Ubuntu 26.04 configura o Apache apenas na porta 80, e a página de instalação deixa o HTTPS ao seu cuidado. O Certbot instala o certificado Let’s Encrypt, adapta o Apache e renova o certificado por si próprio. No Nginx, substitua --apache por --nginx.

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

Passe depois o endereço para HTTPS no .env. APP_URL deve corresponder exatamente ao endereço de visita, prefixo incluído: um desvio nota-se por estilos ausentes, ícones desmedidos e menus quebrados. Um endereço em https ativa por si próprio os cookies seguros.

APP_URL=https://docs.example.com

Se já existirem páginas, as suas ligações guardam o endereço antigo na base de dados. Faça a cópia de segurança da base de dados e execute depois o comando do projeto:

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

O BookStack serve-se na raiz de um domínio ou de um subdomínio, e a documentação descreve também uma instalação sob uma subpasta, como example.com/bookstack. Se um proxy inverso se juntar à frente do Apache, declare o seu endereço em APP_PROXIES: sem ele, o registo de auditoria e a limitação de débito veem o endereço do proxy em vez do dos visitantes. A documentação reserva APP_PROXIES="*" ao diagnóstico.

Onde vivem os seus dados

Mantenha a mesma APP_KEY ao longo do tempo e guarde uma cópia. O BookStack serve-se dela para cifrar nomeadamente os segredos da autenticação de dois fatores: mudá-la pode quebrar estas funcionalidades, e desde a versão 26.09 a aplicação devolve um erro se ela faltar.

As imagens são públicas por predefinição

Com o armazenamento predefinido, o servidor web serve diretamente as imagens, o que é rápido, e qualquer pessoa que conheça o seu endereço pode abri-las. Para uma documentação interna, a escolha faz-se em STORAGE_TYPE:

Para os ficheiros pesados, três definições têm de estar de acordo: FILE_UPLOAD_SIZE_LIMIT no .env, post_max_size e upload_max_filesize no php.ini, e client_max_body_size no Nginx, que vale 1 MB por predefinição.

Duas definições contam também para uma documentação viva: cada página guarda 100 revisões por predefinição (REVISION_LIMIT), e a reciclagem conserva os elementos eliminados durante 30 dias (RECYCLE_BIN_LIFETIME).

Os e-mails: SMTP e fila de espera

O BookStack envia e-mails para a confirmação dos endereços, o esquecimento da palavra-passe, os convites e as notificações. A partir de um VPS Simafri, o envio passa por uma retransmissão SMTP autenticada, na porta 587: o endereço de uma conta de correio que já tenha, ou o 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

Verifique o resultado em «Settings», «Maintenance», com a ação «Send a Test Email», que mostra os erros encontrados. Uma falha durante um convite aparece no ecrã, ao passo que uma falha de notificação fica no registo da aplicação.

Enviar em segundo plano

Por predefinição, o BookStack envia e-mails e webhooks durante o pedido, o que pode abrandar as páginas. Para passar para segundo plano, escreva QUEUE_CONNECTION=database no .env e faça correr um serviço, com o exemplo que a documentação dá para uma instalação Ubuntu por 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

Proteger a sua instância BookStack

A documentação de segurança dá uma lista a retomar logo na instalação:

1. Mude o endereço e a palavra-passe do primeiro administrador.
2. Verifique que o servidor web serve apenas a pasta public, sobretudo se o BookStack viver em /var/www.
3. Limite o utilizador da base de dados apenas à base de dados do BookStack.
4. Preencha APP_URL, para que os endereços gerados pelo sistema não possam ser manipulados.
5. Reveja as definições de inscrição e de acesso público e depois as funções.

A autenticação de dois fatores impõe-se em seguida por função. Inscreva-se também na lista de difusão de segurança do projeto, para receber os seus alertas. O endereço /status serve para uma supervisão: responde 200 quando tudo vai bem, e um código de erro igual ou superior a 400 caso contrário.

O PHP conta tanto como o BookStack. O projeto publicou a 21 de outubro de 2026 um alerta sobre uma atualização crítica do PHP, corrigida na 8.5.12, 8.4.27, 8.3.36 e 8.2.35. O Ubuntu publica estas correções sob os seus próprios números de pacotes, como 8.3.6-0ubuntu0.24.04.13 para o Ubuntu 24.04.

Para os seus conteúdos, mantenha a filtragem ativada por predefinição e reserve o seu abrandamento às instâncias em que só pessoas de confiança escrevem. Se uma conta de administrador se perder, php artisan bookstack:create-admin cria outra, e php artisan bookstack:reset-mfa retira a autenticação de dois fatores de um utilizador.

Cópias de segurança e atualizações

Uma cópia de segurança completa reúne a base de dados e as quatro localizações de ficheiros próprias da sua instância. As exportações de conteúdo servem para outra coisa: a documentação esclarece que não substituem uma cópia de segurança.

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

A primeira linha visa uma instalação por script, em que o root do MySQL se liga por sudo; noutros casos, escreva mysqldump -u bookstack -p bookstack. Arrume estes dois ficheiros à parte, de preferência noutra máquina. O arquivo contém o .env, logo a APP_KEY e as suas palavras-passe: trate-o como um segredo.

Restaurar

Numa máquina nova, instale o BookStack sem executar php artisan migrate, um passo a pôr em comentário no script se o utilizar, e restaure depois a base de dados e os ficheiros, mantendo a APP_KEY de origem:

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

Se a versão instalada for mais recente do que a cópia de segurança, execute depois php artisan migrate. Restabeleça os direitos de escrita do servidor web nas pastas restauradas. Se o endereço tiver mudado, corrija APP_URL e execute bookstack:update-url.

Atualizar

Faça a cópia de segurança da base de dados e dos ficheiros antes de cada atualização e depois, a partir da pasta do BookStack:

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

O script para o Ubuntu 26.04 instala o BookStack sem o Composer. A página das atualizações propõe então, em beta, ./bookstack-system-cli download-vendor em vez de composer install --no-dev. Essa mesma ferramenta sabe copiar e restaurar, mas o projeto ainda não a considera pronta para a produção: teste-a antes de confiar nela.

A documentação mantém uma lista de indicações próprias de cada versão, a ler para a versão visada. Alguns exemplos:

• Versão 26.09: a APP_KEY passa a ser obrigatória.
• Versão 26.05: a pasta storage/fonts deve continuar com permissão de escrita para o servidor web, sem o que as exportações PDF podem falhar.
• Versão 26.03: experimente o envio de e-mails depois da atualização.
• Versão 25.11: grandes alterações da base de dados, cuja migração pode demorar vários minutos numa instância grande.

As falhas corrigem-se em versões de manutenção, como a 26.09.3 de 11 de novembro de 2026: as imagens e os desenhos de uma página em rascunho ou na reciclagem continuavam acessíveis e modificáveis, e o rascunho pessoal de um editor podia ficar visível para outras pessoas.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o BookStack continua a ser o seu software, com as suas definições e os seus dados.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.