Hospedar BookStack em um VPS gerenciado: sua documentação em seu servidor

O que o BookStack faz

O BookStack é uma plataforma de documentação pensada para continuar simples: o README dele visa uma adoção imediata, com apenas noções de processamento de texto. Suas equipes escrevem nele seus procedimentos, sua documentação e sua base de conhecimento, em um navegador, em português se quiserem.

• Quatro níveis de organização: as estantes reúnem livros, os livros contêm capítulos e páginas, os capítulos são opcionais, e o conteúdo vive nas páginas.
• Dois editores: um editor visual padrão e um editor Markdown com visualização ao vivo, aos quais se somam os diagramas do diagrams.net.
• A busca: 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 estante, um livro, um capítulo ou uma página.
• Os logins: e-mail e senha, OpenID Connect, SAML 2.0, LDAP, com uma autenticação em duas etapas por aplicativo ou por códigos de reserva, que pode ser imposta por função.
• O acompanhamento e as trocas: o histórico de 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 suas escolhas: o README dele esclarece que o BookStack não foi concebido como uma plataforma extensível para outros usos, e ele continua fiel à documentação. A renderização de PDF passa pelo dompdf, sem instalação adicional, com capacidades limitadas; o projeto documenta outros motores com EXPORT_PDF_COMMAND.

O que a licença MIT permite

O BookStack é publicado sob a licença MIT por Dan Brown e pelos colaboradores do projeto. Ela autoriza qualquer uso, qualquer modificação e qualquer distribuição, com uma condição: manter o aviso de copyright e o texto da licença em toda cópia do software. O FAQ do projeto esclarece que essa atribuição diz respeito ao código que você compartilha: nada obriga você a exibir o nome ou o logotipo do BookStack em sua instância.

O projeto mantém uma única versão, livre e gratuita: ele não oferece edição empresarial e não tem hospedagem oficial, nem plano de abrir uma. Em compensação, vende planos de suporte, que contribuem para o financiamento dele junto com as doações e os patrocínios. O BookStack é instalado, portanto, em seu servidor, sem licença a comprar.

Os requisitos do BookStack

O Docker continua opcional. O projeto não publica imagem oficial: as instalações em contêiner vêm de projetos da comunidade, LinuxServer.io e solidnerd. Este guia segue o caminho oficial, PHP e MySQL diretamente no servidor, que não exige nada além disso.

A documentação descarta a hospedagem PHP compartilhada: o BookStack exige um servidor que você administra. Ela não informa a memória nem o processador necessários. Em um VPS gerenciado, descreva-nos o uso, o número de pessoas e o volume de imagens e anexos, e recomendamos o tamanho adequado.

A instalação do BookStack

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

Com o script do projeto, em um Ubuntu recém-instalado

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

Esses scripts são reservados a um sistema recém-instalado: eles podem sobrescrever uma configuração web existente. Também deixam de lado dois assuntos, as configurações de e-mail e a segurança do sistema, a prever à parte.

O script coloca o BookStack em /var/www/bookstack. O do Ubuntu 26.04 pede o domínio e o endereço da conta de administrador e exibe no fim uma senha gerada ao acaso, ausente do log dele: anote-a. Com outro script, anote os acessos exibidos no fim e mude qualquer acesso padrão no primeiro login.

À mão, em qualquer outra máquina

Comece pelo banco de dados: um banco e um usuário limitado a esse banco. O script do projeto procede assim, com a senha de 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 em seguida o ramo 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 o banco 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 o Apache, ou quando os arquivos .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 com a conta admin@admin.com e a senha password. Mude o endereço e a senha no primeiro login.

HTTPS e APP_URL

Os visitantes chegam pelas portas 80 e 443, sob o nome de domínio do servidor. Crie para esse nome registros A e AAAA e peça o certificado: o script do Ubuntu 26.04 configura o Apache só na porta 80, e a página de instalação deixa o HTTPS por sua conta. O Certbot instala o certificado Let's Encrypt, adapta o Apache e renova o certificado por conta própria. No Nginx, troque --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 em seguida o endereço para HTTPS no .env. APP_URL deve corresponder exatamente ao endereço de visita, prefixo incluído: uma diferença aparece como estilos ausentes, ícones desproporcionais e menus quebrados. Um endereço em https ativa sozinho os cookies seguros.

APP_URL=https://docs.example.com

Se já existem páginas, os links delas mantêm o endereço antigo no banco. Faça backup do banco e execute o comando do projeto:

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

O BookStack é servido na raiz de um domínio ou subdomínio, e a documentação também descreve uma instalação em uma subpasta, como example.com/bookstack. Se um proxy reverso entrar na frente do Apache, declare o endereço dele em APP_PROXIES: sem isso, o registro de auditoria e a limitação de taxa veem o endereço do proxy no lugar do dos visitantes. A documentação reserva APP_PROXIES="*" ao diagnóstico.

Onde vivem seus dados

Mantenha a mesma APP_KEY ao longo do tempo e faça backup dela. O BookStack a usa para criptografar, entre outras coisas, os segredos da autenticação em duas etapas: mudá-la pode quebrar essas funções, e desde a versão 26.09 a aplicação devolve um erro se ela estiver ausente.

As imagens são públicas por padrão

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

Para arquivos pesados, três configurações precisam concordar: 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 padrão.

Duas configurações também contam para uma documentação viva: cada página guarda 100 revisões por padrão (REVISION_LIMIT), e a lixeira conserva os itens excluídos por 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 de senha, os convites e as notificações. A partir de um VPS Simafri, o envio passa por um relay SMTP autenticado, na porta 587: o endereço de uma conta de e-mail que você já tem, 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 em um convite aparece na tela, enquanto uma falha de notificação fica no log da aplicação.

Enviar em segundo plano

Por padrão, o BookStack envia e-mails e webhooks durante a requisição, o que pode deixar as páginas lentas. Para passar ao segundo plano, escreva QUEUE_CONNECTION=database no .env e rode 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 sua instância BookStack

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

1. Mude o endereço e a senha do primeiro administrador.
2. Verifique se o servidor web serve somente a pasta public, sobretudo se o BookStack vive em /var/www.
3. Limite o usuário do banco ao banco do BookStack apenas.
4. Preencha APP_URL, para que os endereços gerados pelo sistema não possam ser manipulados.
5. Releia as configurações de cadastro e de acesso público e depois as funções.

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

O PHP conta tanto quanto o BookStack. O projeto publicou em 21 de outubro de 2026 um alerta sobre uma atualização crítica do PHP, corrigida nas versões 8.5.12, 8.4.27, 8.3.36 e 8.2.35. O Ubuntu publica essas correções com os próprios números de pacote, como 8.3.6-0ubuntu0.24.04.13 para o Ubuntu 24.04.

Para seus conteúdos, mantenha a filtragem ativada por padrão e reserve o relaxamento dela às instâncias em que apenas 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 remove a autenticação em duas etapas de um usuário.

Backups e atualizações

Um backup completo reúne o banco e os quatro locais de arquivos próprios de sua instância. As exportações de conteúdo servem a outra coisa: a documentação esclarece que elas não substituem um backup.

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 conecta por sudo; em outros casos, escreva mysqldump -u bookstack -p bookstack. Guarde esses dois arquivos à parte, de preferência em outra máquina. O arquivo compactado contém o .env, portanto a APP_KEY e suas senhas: trate-o como um segredo.

Restaurar

Em uma máquina nova, instale o BookStack sem executar php artisan migrate, etapa a comentar no script se você o usar, e restaure o banco e os arquivos, mantendo a APP_KEY original:

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

Se a versão instalada for mais recente que o backup, execute então php artisan migrate. Devolva os direitos de escrita do servidor web às pastas restauradas. Se o endereço mudou, corrija APP_URL e execute bookstack:update-url.

Atualizar

Faça backup do banco e dos arquivos antes de cada atualização e, 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 no lugar de composer install --no-dev. Essa mesma ferramenta sabe fazer backup 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 orientaçõ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 em PDF podem falhar.
• Versão 26.03: teste o envio de e-mails depois da atualização.
• Versão 25.11: grandes mudanças no banco, cuja migração pode levar vários minutos em uma instância grande.

As falhas são corrigidas 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 lixeira continuavam acessíveis e modificáveis, e o rascunho pessoal de um editor podia aparecer para outras pessoas.

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o BookStack continua sendo seu software, com as configurações e os dados dele.

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.