Como Instalar BookStack em VPS Linux para Documentação

Por que escolher o BookStack para sua Wiki Self-Hosted?

No cenário atual de infraestrutura de TI e desenvolvimento de software, a documentação é tão crítica quanto o código em si. Equipes distribuídas precisam de uma fonte única da verdade, acessível, rápida e fácil de manter. O BookStack emergiu como uma das melhores alternativas ao GitBook e outras plataformas proprietárias, oferecendo uma solução de wiki self-hosted robusta, open-source e baseada em PHP (Laravel). Diferente de wikis tradicionais baseadas em texto markdown puro ou MediaWiki, o BookStack foca na estrutura hierárquica: Livros > Capítulos > Páginas, facilitando a organização lógica do conhecimento.

Instalar o BookStack em um ambiente VPS Linux garante controle total sobre os dados, segurança e personalização. Este tutorial técnico guiará você pela instalação completa utilizando Nginx, PHP 8.x, MySQL/MariaDB e Git, preparando o servidor para produção com as melhores práticas de segurança.

Pré-requisitos de Infraestrutura

Antes de iniciar a instalação, certifique-se de que sua VPS atenda aos requisitos mínimos. Embora o BookStack seja leve, ele opera uma aplicação web dinâmica com banco de dados relacional.

• Sistema Operacional: Ubuntu 20.04 LTS, 22.04 LTS ou Debian 11/12 (recomendado).
• Recursos: Mínimo de 512MB de RAM (recomendado 1GB para bom desempenho) e 1 vCPU.
• Acesso: Acesso root ou usuário com privilégios sudo.
• Dominio: Um domínio apontando para o IP da sua VPS (opcional, mas recomendado para HTTPS).

Comece atualizando o índice de pacotes do seu sistema operacional para garantir que você está instalando as versões mais recentes das dependências.

sudo apt update && sudo apt upgrade -y

Passo 1: Instalação e Configuração do Banco de Dados (MySQL/MariaDB)

O BookStack utiliza um banco de dados relacional para armazenar conteúdo, usuários e permissões. Vamos utilizar o MySQL ou MariaDB. Neste guia, usaremos mysql-server, mas o processo é idêntico para mariadb-server.

Instale o servidor do banco de dados:

sudo apt install mysql-server -y

Após a instalação, execute o script de segurança inicial para remover configurações padrão inseguras:

sudo mysql_secure_installation

Siga as instruções no terminal. Geralmente, você deve responder y (yes) para todas as perguntas, especialmente para configurar o "VALIDATE PASSWORD COMPONENT" e definir uma senha forte para o root do MySQL.

Agora, crie o banco de dados e o usuário dedicado para o BookStack. Entre no shell do MySQL:

sudo mysql

Dentro do prompt do MySQL, execute os seguintes comandos SQL (substitua bookstackuser e sua_senha_forte por credenciais reais):

CREATE DATABASE bookstack_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstackuser'@'localhost' IDENTIFIED BY 'sua_senha_forte';
GRANT ALL PRIVILEGES ON bookstack_db.* TO 'bookstackuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Com isso, temos o banco de dados preparado e isolado para a aplicação.

Passo 2: Instalação do PHP e Dependências

O BookStack é construído sobre o framework Laravel, o que exige uma versão específica do PHP e diversas extensões. A maioria das versões modernas do Ubuntu/Debian já vem com PHP 8.1 ou 8.2, mas vamos garantir que todas as dependências necessárias estejam instaladas.

sudo apt install php8.1-fpm php8.1-mysql php8.1-common php8.1-mbstring php8.1-xmlrpc php8.1-gd php8.1-xml php8.1-cli php8.1-zip php8.1-curl php8.1-bcmath php8.1-intl subversion imagemagick libmagickwand-dev git -y

Nota importante: Verifique a versão do PHP instalada com php -v. Se seu sistema tiver PHP 8.2, substitua todas as ocorrências de php8.1 no comando acima por php8.2.

Além das extensões básicas, o BookStack requer suporte a bibliotecas específicas para processamento de imagens e conversão de PDFs (se você planeja exportar documentação). O pacote imagemagick já foi incluído acima.

Passo 3: Configuração do Nginx

O Nginx será nosso servidor web, responsável por servir os arquivos estáticos e passar as requisições PHP para o processador FPM. Criaremos um arquivo de configuração de servidor virtual.

Crie o arquivo de configuração:

sudo nano /etc/nginx/sites-available/bookstack

Cole a seguinte configuração, ajustando o server_name para seu domínio ou IP:

server {
    listen 80;
    server_name wiki.seudominio.com; # Altere para seu domínio ou IP

    root /var/www/bookstack/public;
    index index.php;

    charset utf8mb4;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # Ajuste a versão do PHP se necessário
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }

    client_max_body_size 10M;
}

Atenção: Se você estiver usando PHP 8.2, altere a linha fastcgi_pass para unix:/var/run/php/php8.2-fpm.sock;.

Ative o site e teste a configuração do Nginx:

sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
sudo nginx -t

Se o teste retornar syntax is ok e test is successful, recarregue o serviço:

sudo systemctl reload nginx

Passo 4: Download e Configuração do BookStack

Agora vamos baixar o código-fonte do BookStack. Recomendamos instalar a versão estável (release) em vez da branch master para garantir estabilidade em produção.

sudo mkdir -p /var/www/bookstack
cd /var/www/bookstack
sudo git clone https://github.com/BookStackApp/BookStack.git . --branch release --single-branch

O parâmetro --branch release garante que você pegue a última versão estável disponível no repositório.

Copie o arquivo de configuração de exemplo:

sudo cp .env.example .env

Edite o arquivo .env para inserir as credenciais do banco de dados criadas no Passo 1:

sudo nano .env

Altere as seguintes linhas conforme seus dados:

DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=bookstack_db
DB_USERNAME=bookstackuser
DB_PASSWORD=sua_senha_forte

Gere uma chave de aplicação única e segura. O BookStack precisa disso para criptografar sessões e tokens:

sudo php artisan key:generate

Instale as dependências do Composer (gerenciador de pacotes PHP):

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
sudo composer install --no-dev --optimize-autoloader

Por fim, execute as migrações do banco de dados para criar as tabelas necessárias:

sudo php artisan migrate

Passo 5: Permissões e Usuário do Sistema

Para segurança, não rodaremos o BookStack como root. Vamos criar um usuário dedicado e ajustar as permissões de diretório.

sudo useradd -r -s /bin/false bookstack
sudo chown -R bookstack:bookstack /var/www/bookstack

O arquivo .env deve ter permissões restritas:

sudo chmod 640 /var/www/bookstack/.env

Passo 6: Configuração do Supervisor (Gerenciamento de Processos)

O BookStack requer processos em segundo plano para manipular filas de tarefas (como envio de emails, geração de thumbnails e sincronização). O Supervisor é a ferramenta padrão no Linux para manter esses processos rodando.

Instale o Supervisor:

sudo apt install supervisor -y

Crie um arquivo de configuração para o BookStack no diretório do Supervisor:

sudo nano /etc/supervisor/conf.d/bookstack.conf

Insira a seguinte configuração:

[program:bookstack]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/bookstack/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=bookstack
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/bookstack/storage/logs/queue.log

Recarregue a configuração do Supervisor e inicie os processos:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start bookstack:

Passo 7: Segurança Final (HTTPS e Firewall)

Em produção, uma wiki deve ser acessada via HTTPS. Utilize o Certbot para obter certificados gratuitos do Let's Encrypt.

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d wiki.seudominio.com

O assistente do Certbot irá redirecionar automaticamente o tráfego HTTP para HTTPS e renovar os certificados. Aceite as condições e insira seu email de contato.

Verifique se o firewall (UFW) está permitindo apenas as portas necessárias:

sudo ufw allow 'Nginx Full'
sudo ufw enable

Primeiro Acesso e Configuração Inicial

Abra seu navegador e acesse https://wiki.seudominio.com. Você será recebido pela tela de login.

O BookStack cria automaticamente um usuário administrador na primeira inicialização. As credenciais padrão são:

• Email: admin@example.com
• Senha: password

Ação Imediata: Faça login e altere a senha e o email imediatamente nas configurações do perfil. Além disso, vá em Administração > Configurações para ajustar o nome da organização, idioma e opções de autenticação (como ativar 2FA se necessário).

Manutenção e Backup

Para manter sua instalação segura e funcional, realize backups regulares. Um backup completo envolve dois componentes:

1. Banco de Dados: mysqldump -u bookstackuser -p bookstack_db > backup_$(date +%F).sql
2. Diretório da Aplicação: Inclui uploads, logs e o arquivo .env. Faça um dump do diretório /var/www/bookstack.

Para atualizações futuras, navegue até o diretório de instalação e execute:

cd /var/www/bookstack
sudo git pull origin release
sudo composer install --no-dev --optimize-autoloader
sudo php artisan migrate

Este guia fornece uma base sólida para uma knowledge base profissional. Com o BookStack rodando em sua VPS, sua equipe terá uma ferramenta poderosa para estruturar documentação técnica, manuais de procedimento e wikis de projeto, tudo sob seu controle total.