Como Instalar o BookStack em VPS Linux: Guia Completo

A documentação técnica é o coração de qualquer equipe de engenharia ou operação de TI eficaz. Sem um repositório centralizado e bem estruturado, o conhecimento tribal se perde, onboarding se torna lento e a resolução de incidentes fica comprometida. O BookStack se destaca como uma das melhores soluções open source para criar wikis corporativas, bases de conhecimento e manuais técnicos. Ele oferece uma estrutura hierárquica intuitiva (Livros > Capítulos > Páginas) que facilita a organização complexa de informações.

Neste tutorial, vamos guiar você pelo processo completo de instalar bookstack vps utilizando um servidor Linux com stack LAMP (Linux, Apache, MySQL/MariaDB e PHP). Esta configuração é ideal para ambientes hospedagem vps padrão, garantindo performance, segurança e facilidade de manutenção. Ao final deste guia, você terá uma wiki self-hosted funcional, pronta para receber o conhecimento da sua equipe.

Pré-requisitos e Preparação do Ambiente

Antes de iniciar a instalação do aplicativo em si, é fundamental garantir que o servidor esteja atualizado e com as dependências básicas instaladas. Vamos utilizar um sistema operacional baseado em Debian/Ubuntu, como Ubuntu Server ou Debian 11/12, devido à sua ampla adoção no ecossistema linux tutorial.

Primeiro, conecte-se ao seu servidor via SSH e atualize o índice de pacotes:

sudo apt update && sudo apt upgrade -y

O BookStack requer PHP 8.1 ou superior para funcionar corretamente nas versões mais recentes. Além disso, é necessário instalar o Apache como servidor web, o MariaDB (ou MySQL) como banco de dados e as extensões PHP necessárias. Execute o seguinte comando para instalar todos os pacotes essenciais de uma vez:

sudo apt install apache2 mariadb-server libapache2-mod-php8.1 php8.1 php8.1-mysql php8.1-curl php8.1-gd php8.1-intl php8.1-mbstring php8.1-xml php8.1-zip php8.1-bcmath composer -y

Após a instalação, inicie e habilite o serviço do banco de dados para que ele rode automaticamente em caso de reinicialização do servidor:

sudo systemctl enable mariadb --now
sudo systemctl start apache2

Configuração do Banco de Dados

O BookStack utiliza um banco de dados relacional para armazenar usuários, permissões e o conteúdo das páginas. Vamos criar uma base de dados dedicada e um usuário com privilégios restritos para garantir a segurança da nossa knowledge base.

Inicie o script de segurança do MariaDB:

sudo mysql_secure_installation

Siga as instruções na tela. Geralmente, você deve definir uma senha root para o banco de dados e responder "Y" (Sim) para todas as perguntas subsequentes (remover usuário anônimo, remover acesso root remoto, remover banco de dados de teste).

Agora, acesse o shell do MySQL para criar o banco de dados e o usuário:

sudo mysql -u root -p

Dentro do prompt do MySQL, execute os seguintes comandos. Substitua bookstackdb, usuario_bookstack e senha_forte_aqui por nomes e senhas reais:

CREATE DATABASE bookstackdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'usuario_bookstack'@'localhost' IDENTIFIED BY 'senha_forte_aqui';
GRANT ALL PRIVILEGES ON bookstackdb.* TO 'usuario_bookstack'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Com o banco de dados configurado, estamos prontos para baixar e configurar a aplicação.

Baixando e Configurando o BookStack

A maneira mais robusta de instalar o BookStack é utilizando o Git para clonar o repositório oficial e o Composer para gerenciar as dependências do PHP. Isso facilita futuras atualizações e garante que você tenha controle sobre a versão instalada.

Crie um diretório para a aplicação:

sudo mkdir /var/www/bookstack
sudo chown -R $USER:$USER /var/www/bookstack

Navegue até o diretório e clone o repositório. Para produção, recomenda-se usar a tag da versão estável mais recente em vez do branch main:

cd /var/www/bookstack
git clone --branch master https://github.com/BookStackApp/BookStack.git .

Instale as dependências do PHP usando o Composer. Certifique-se de estar no diretório onde os arquivos foram clonados:

sudo -u www-data composer install --no-dev --optimize-autoloader

Agora, copie o arquivo de configuração de exemplo e edite-o para inserir as credenciais do banco de dados criadas anteriormente:

cp .env.example .env
sudo nano .env

Dentro do arquivo .env, localize as seguintes linhas e ajuste os valores conforme necessário. É crucial gerar uma chave de aplicativo segura:

DB_DATABASE=bookstackdb
DB_USERNAME=usuario_bookstack
DB_PASSWORD=senha_forte_aqui
APP_KEY=base64:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Para gerar a chave APP_KEY, execute o seguinte comando no terminal do servidor:

php artisan key:generate --show

Copie a saída desse comando e substitua o valor em APP_KEY no arquivo de configuração. Salve e saia do editor.

Configuração do Servidor Web Apache

O Apache precisa saber como servir os arquivos do BookStack. Precisamos criar um Virtual Host apontando para o diretório public da aplicação, que é a raiz web segura do framework Laravel utilizado pelo BookStack.

Crie um arquivo de configuração:

sudo nano /etc/apache2/sites-available/bookstack.conf

Cole o seguinte conteúdo, ajustando o ServerName para o domínio ou IP do seu servidor:

<VirtualHost *:80>
    ServerName docs.seudominio.com
    DocumentRoot /var/www/bookstack/public

    <Directory /var/www/bookstack/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/bookstack_error.log
    CustomLog ${APACHE_LOG_DIR}/bookstack_access.log combined
</VirtualHost>

Habilite o Virtual Host e o módulo de reescrita de URL do Apache (necessário para URLs amigáveis):

sudo a2ensite bookstack.conf
sudo a2enmod rewrite

Reinicie o serviço Apache para aplicar as mudanças:

sudo systemctl restart apache2

Finalizando a Instalação e Acesso Web

Com tudo configurado, execute o comando de instalação final do Artisan. Isso criará as tabelas no banco de dados e inicializará a estrutura interna:

cd /var/www/bookstack
sudo -u www-data php artisan bookstack:install

O sistema pedirá que você crie o usuário administrador inicial. Forneça um email, nome de usuário e senha fortes. Este será o seu acesso root na plataforma.

Agora, abra seu navegador e acesse http://docs.seudominio.com (ou o IP do servidor). Você verá a tela de login do BookStack. Faça login com as credenciais criadas no passo anterior.

Habilitando HTTPS e Segurança

Uma wiki self-hosted que contém dados sensíveis da empresa deve ser acessada via HTTPS. A maneira mais simples e eficaz de obter um certificado SSL gratuito é utilizando o Let's Encrypt com o Certbot.

Instale o Certbot e o plugin para Apache:

sudo apt install certbot python3-certbot-apache -y

Rode o comando para gerar o certificado. O assistente irá detectar seu Virtual Host e perguntará se deseja redirecionar HTTP para HTTPS:

sudo certbot --apache -d docs.seudominio.com

Siga as instruções na tela. Certifique-se de selecionar a opção 2 (Redirecionar todo o tráfego para HTTPS) quando solicitado. O Certbot configurará automaticamente os certificados e reiniciará o Apache.

Para garantir que seus certificados sejam renovados automaticamente, verifique se o cronjob do certbot está ativo:

sudo systemctl enable --now certbot

Configurações Avançadas e Boas Práticas

Para manter sua documentação estruturada segura e performática, considere as seguintes configurações adicionais no arquivo .env e nas permissões do servidor.

Ajustes de Memória e Timeout

O BookStack pode ser pesado em operações de importação/exportação ou renderização de páginas complexas. Edite o arquivo de configuração do PHP (/etc/php/8.1/apache2/php.ini) para aumentar os limites de memória e tempo de execução:

memory_limit = 256M
max_execution_time = 300
upload_max_filesize = 20M
post_max_size = 20M

Após alterar o php.ini, reinicie o Apache:

sudo systemctl restart apache2

Permissões de Arquivos

O BookStack precisa escrever em alguns diretórios para armazenar uploads e caches. Garanta que o usuário do Apache (www-data) tenha as permissões corretas:

sudo chown -R www-data:www-data /var/www/bookstack/storage
sudo chown -R www-data:www-data /var/www/bookstack/bootstrap/cache

Backup Automático

A integridade dos dados é primordial. Configure um backup diário do banco de dados e dos arquivos de upload (localizados em /var/www/bookstack/storage/uploads). Um script simples usando cron pode compactar e enviar esses dados para um armazenamento externo ou outro servidor.

Exemplo de comando de backup via terminal:

# Backup do banco de dados
mysqldump -u usuario_bookstack -p bookstackdb > /backup/bookstack_db_$(date +%F).sql

# Backup dos arquivos (opcional, se usar armazenamento externo para uploads)
tar -czf /backup/bookstack_files_$(date +%F).tar.gz /var/www/bookstack/storage/uploads

Conclusão

Parabéns! Você concluiu o processo de instalar bookstack vps. Sua nova plataforma de documentação estruturada está online, segura e pronta para ser utilizada. O BookStack oferece uma experiência de usuário superior a wikis tradicionais baseadas em texto puro, graças à sua interface moderna e organização visual.

Agora que a infraestrutura está pronta, encourage suas equipes a começarem a migrar seus documentos do Confluence, Notion ou notas soltas para esta nova knowledge base. A estrutura de Livros e Capítulos ajuda a manter o caos documental sob controle, facilitando a busca e a descoberta de informações técnicas.

Lembre-se de monitorar os logs do Apache e do PHP em caso de erros e atualizar o BookStack regularmente seguindo as instruções oficiais de atualização via Git. Uma app open source bem mantida garante longevidade e controle total sobre a sua infraestrutura de conhecimento.