Implantação de Base de Conhecimento - Wiki Interna com BookStack

Olá, comunidade DIO!

Vamos resolver o problema da documentação dispersa de uma vez por todas? Que tal implantarmos juntos o BookStack hoje?

Converso diariamente com profissionais que enfrentam o mesmo "vilão" silencioso: a descentralização da informação. Já parou para pensar quanto tempo sua equipe perde procurando aquele PDF de configuração enviado no WhatsApp há três meses? Ou pior, quando um processo crítico só existe na cabeça de um colaborador que saiu de férias?

O conhecimento é o ativo mais valioso de um time de TI, mas quando ele está disperso, ele se torna um gargalo. É para resolver esse caos que apresento o BookStack. Ele é uma ferramenta Open Source fantástica que organiza sua documentação em uma estrutura lógica de Prateleiras, Livros, Capítulos e Páginas. É como ter uma biblioteca técnica profissional, pesquisável e colaborativa dentro da sua infraestrutura.

Master Guide: Implantação do BookStack Nativo

Este roteiro é um Procedimento Operacional Padrão (POP) para Debian 13 ou Ubuntu 24.04+.

⚠️ Atenção:

Execução Linha a Linha

Para garantir o sucesso, copie e cole os comandos bash individualmente. Evite blocos grandes para que o terminal não ignore instruções importantes.

Uma nota importante sobre Segurança (HTTP vs HTTPS)

Neste guia de laboratório, utilizaremos o protocolo HTTP. Configurar certificados (SSL) exige um domínio registrado ou configurações complexas de CA interna. Para que seu laboratório suba de primeira e sem erros de "Conexão Não Segura" , focaremos na entrega do serviço funcional. Em um ambiente de produção real, o próximo passo seria implementar o SSL, mas aqui o objetivo é colocar sua base de conhecimento no ar com agilidade!

Acesso Remoto e Segurança SSH (se necessário)

O SSH permite administrar o servidor confortavelmente pelo seu Windows. Como o Linux recusa conexões de usuários sem senha, vamos definir a sua agora.

Ação: Instale o serviço e execute o comando de senha (substitua SEU_USUARIO pelo seu login no Linux, ex: live ou ubuntu):

sudo apt update && sudo apt install -y openssh-server
sudo passwd SEU_USUARIO

O que acontece agora? O Linux pedirá interatividade:

New password: Digite sua senha (os caracteres não aparecem por segurança). Aperte Enter.
Retype new password: Digite a mesma senha novamente. Aperte Enter.

sudo service ssh start || sudo systemctl enable --now ssh

Dica: Se você recriou sua VM e o Windows deu erro de "REMOTE HOST IDENTIFICATION HAS CHANGED", rode este comando no terminal do seu Windows para limpar a memória do IP: ssh-keygen -R IP_DA_SUA_VM

Checkpoint: No seu Windows, abra o CMD e digite ssh SEU_USUARIO@IP_DA_VM. Se você conseguir logar, o acesso remoto está validado!

Preparação da Stack de Software (LAMP)

Instalaremos o "motor" do sistema: Apache (Web), MariaDB (Banco) e o PHP 8.x.

sudo apt install -y apache2 mariadb-server git curl composer php php-mysql php-xml php-mbstring php-curl php-zip php-gd php-ldap unzip

Checkpoint: Digite php -v. Se o terminal retornar a versão do PHP (ex: 8.2 ou 8.3), o motor básico está instalado.

Banco de Dados

Criaremos o banco de dados usando a senha padrão sugerida: bookstack_db_password.

sudo mysql -u root -e "CREATE DATABASE bookstack;" 
sudo mysql -u root -e "CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'bookstack_db_password';"
sudo mysql -u root -e "GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';"
sudo mysql -u root -e "FLUSH PRIVILEGES;"

Checkpoint: Teste o acesso ao banco com: mysql -u bookstack -p'bookstack_db_password' -e "SHOW DATABASES;" Se o banco bookstack aparecer, está pronto e acessível.

Download da Aplicação

Baixamos os arquivos oficiais e instalamos as bibliotecas via Composer.

sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch /var/www/bookstack
cd /var/www/bookstack
sudo composer install --no-dev
sudo cp .env.example .env

Checkpoint: Digite ls -a. Você deve ver a pasta vendor e o arquivo .env. Isso confirma que o sistema foi baixado e as dependências instaladas.

Automação do Arquivo .env

Estes comandos editam o arquivo automaticamente, capturando seu IP e configurando o acesso ao banco.

Atenção: Garanta que você está na pasta: cd /var/www/bookstack.

cd /var/www/bookstack
MY_IP=$(hostname -I | awk '{print $1}')
sudo sed -i "s|^APP_URL=.*|APP_URL=http://$MY_IP|g" .env
sudo sed -i "s|^APP_DEBUG=.*|APP_DEBUG=true|g" .env
sudo sed -i "s|^DB_DATABASE=.*|DB_DATABASE=bookstack|g" .env
sudo sed -i "s|^DB_USERNAME=.*|DB_USERNAME=bookstack|g" .env
sudo sed -i "s|^DB_PASSWORD=.*|DB_PASSWORD=bookstack_db_password|g" .env

Checkpoint: Verifique os valores com: grep -E "APP_URL|APP_DEBUG|DB_DATABASE|DB_PASSWORD" .env. Se mostrar seu IP e os dados do passo 3, a configuração automática funcionou.

Agora, gere a chave e suba a estrutura:

sudo php artisan config:clear
sudo php artisan key:generate --force
sudo php artisan migrate --force

Governança de Permissões

Fundamental para permitir que o Apache salve suas fotos e documentos (sem isso, o erro 500 é certo).

sudo chown -R www-data: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

Checkpoint: Digite ls -ld storage. O resultado deve começar com drwxrwxr-x e o dono deve ser www-data.

Configuração do Servidor Web (Apache)

Finalizamos criando o endereço do site e ativando os módulos necessários.

sudo bash -c 'cat > /etc/apache2/sites-available/bookstack.conf <<EOF
<VirtualHost *:80>
  DocumentRoot /var/www/bookstack/public
  <Directory /var/www/bookstack/public>
      Options Indexes FollowSymLinks
      AllowOverride All
      Require all granted
  </Directory>
</VirtualHost>
EOF'

sudo a2dissite 000-default.conf && sudo a2ensite bookstack.conf && sudo a2enmod rewrite
sudo service apache2 restart || sudo systemctl restart apache2

Checkpoint: Digite ls /etc/apache2/sites-enabled/. Deve aparecer bookstack.conf. Além disso, o comando sudo service apache2 status deve mostrar o status active (running).

Validação Final: Como acessar.

Descubra seu IP: No terminal, digite hostname -I | awk '{print $1}'.
No Navegador: Digite o IP precedido por http:// (ex: http://10.100.100.147).

⚠️ Atenção: Não use HTTPS. Sem certificado, o site não carregará se você colocar o "S".

Dica de Cache: Se ainda vir a página de teste do Apache, pressione Ctrl + F5.

Credenciais Iniciais:

E-mail:

admin@admin.com

Senha:

password

Guia de Resolução de Problemas (Troubleshooting)

Se algo não saiu como o esperado, identifique o sintoma abaixo e aplique a correção:

Sintoma: Aparece a página "Funciona!" (padrão do Apache) em vez do BookStack.

Causa: O site padrão do Apache ainda está ativo ou o seu navegador guardou a versão antiga na memória (cache).
Correção: Execute sudo a2dissite 000-default.conf seguido de sudo systemctl restart apache2. No seu navegador, use o atalho Ctrl + F5 para forçar a atualização.

Sintoma: Erro HTTP 500 (Tela branca ou mensagem de erro interno).

Causa: Geralmente é falta de permissão nas pastas ou o arquivo .env está mal configurado.
Correção: Refaça o Passo 6 (Governança de Permissões) integralmente. Se persistir, verifique se você rodou o comando sudo php artisan key:generate no Passo 5.
Sintoma: Erro SQLSTATE [1045] - Access denied for user.
Causa: O nome do usuário ou a senha que você colocou no arquivo .env não batem com o que foi criado no banco de dados.
Correção: Verifique se o DB_PASSWORD no Passo 5 é exatamente o mesmo que você definiu no comando CREATE USER do Passo 3. Lembre-se que as aspas e pontos contam!

Sintoma: Erro de "REMOTE HOST IDENTIFICATION HAS CHANGED" no SSH.

Causa: Você deletou a VM antiga e criou uma nova com o mesmo IP, gerando conflito de identidade no Windows.
Correção: No terminal do seu Windows, rode: ssh-keygen -R [IP_DA_VM]. Isso limpa o registro antigo e permite uma nova conexão.

Sintoma: O site não carrega ou dá "Tempo de conexão esgotado".

Causa: O navegador pode estar tentando forçar o uso de HTTPS (protocolo seguro com cadeado) automaticamente.
Correção: Verifique a barra de endereços. Se estiver https://..., apague o "s" e deixe apenas http://. Certifique-se também de que a placa de rede da VM está em modo Bridge.

Anderson Andrade Leite

LinkedIn: linkedin.com/in/anderson-andrade-leite
DIO Campus Expert | Infraestrutura & Suporte

Referências:

Documentação Oficial: BookStack Documentation

Espero que este guia ajude a centralizar o conhecimento e elevar o nível da sua infraestrutura!