Como Instalar o BookStack com Nginx no Ubuntu 20.04

BookStack é uma plataforma auto-hospedada, de código aberto e fácil de usar para organizar e armazenar informações. Pode ser usada para múltiplos propósitos, como um Wiki, site de documentação e aplicativo de anotações. É construída usando o framework PHP Laravel e utiliza MySQL para armazenar os dados. Para fins de edição, oferece a você a escolha entre usar um editor WYSIWYG ou um editor Markdown. Suporta autenticação de múltiplos fatores e modo escuro, e é multilíngue.

Este tutorial ensinará você a instalar o BookStack em um servidor baseado em Ubuntu 20.04.

Pré-requisitos

1. Um servidor rodando Ubuntu 20.04
2. Um Nome de Domínio Totalmente Qualificado (FQDN) apontando para o servidor.
3. Um usuário não-root com privilégios sudo.
4. PHP versão 7.3 ou superior.
5. MySQL>=5.6 e MariaDB>=10.0
6. Git e Composer.

Passo 1 - Configurar o Firewall

O primeiro passo é configurar o firewall. O Ubuntu vem com o ufw (Uncomplicated Firewall) por padrão.

Verifique se o firewall está em execução.

$ sudo ufw status

Você deve obter a seguinte saída.

Status: inactive

Permita a porta SSH para que o firewall não interrompa a conexão atual ao ativá-lo.

$ sudo ufw allow OpenSSH

Permita também as portas HTTP e HTTPS.

$ sudo ufw allow 80
$ sudo ufw allow 443

Ative o Firewall

$ sudo ufw enable
Comando pode interromper conexões ssh existentes. Prosseguir com a operação (y|n)? y
Firewall está ativo e habilitado na inicialização do sistema

Verifique o status do firewall novamente.

$ sudo ufw status

Você deve ver uma saída semelhante.

Status: active

Para                         Ação      De
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Passo 2 - Instalar o Git

O primeiro passo é instalar o Git. Ele será necessário para baixar e atualizar o BookStack. Execute o seguinte comando para instalar o Git.

$ sudo apt install git

Verifique a instalação.

$ git --version

Passo 3 - Instalar PHP e extensões

Como o BookStack depende do PHP, você precisa instalar o PHP e suas extensões.

O Ubuntu vem com uma versão desatualizada do PHP. Primeiro, precisamos adicionar o repositório PHP do Ondrej.

$ sudo add-apt-repository ppa:ondrej/php

Em seguida, instale o PHP e suas extensões necessárias para o BookStack.

$ sudo apt install php7.4-fpm php7.4-mbstring php7.4-gd php7.4-xml unzip php7.4-bcmath php7.4-curl php7.4-mysql

Verifique a instalação.

$ php --version
PHP 7.4.25 (cli) (built: Oct 22 2021 12:34:33) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.25, Copyright (c), by Zend Technologies

Passo 4 - Instalar e Configurar o MariaDB

O Ubuntu vem com uma versão mais antiga do MariaDB. Para instalar a versão mais recente, adicione o repositório oficial do MariaDB. Execute os seguintes comandos para adicionar o repositório.

$ curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup
$ sudo bash mariadb_repo_setup --mariadb-server-version=10.6

Execute o seguinte comando para instalar o servidor MariaDB.

$ sudo apt install mariadb-server

Proteja a instalação do MariaDB.

$ sudo mysql_secure_installation

Você enfrentará vários prompts. Responda-os da seguinte forma.

Digite a senha atual para root (pressione Enter para nenhum): Pressione Enter
Mudar para autenticação unix_socket [Y/n] Digite y
Alterar a senha do root? [Y/n] Digite n
Remover usuários anônimos? [Y/n] Digite y
Desabilitar login remoto do root? [Y/n] Digite y
Remover banco de dados de teste e acesso a ele? [Y/n] Digite y
Recarregar tabelas de privilégios agora? [Y/n] Digite y

Conecte-se ao shell do MariaDB usando o seguinte comando.

$ sudo mysql

Crie um novo banco de dados para o Bookstack.

$ create database bookstack;

Crie um novo usuário de banco de dados.

$ CREATE USER 'bookstackuser'@'localhost' identified by 'bookstackpassword';

Escolha uma senha forte.

Conceda permissões no banco de dados ao usuário.

$ grant CREATE,ALTER,SELECT,INSERT,UPDATE,DELETE on `bookstack`.* to 'bookstackuser'@'localhost';

Saia do shell do MySQL.

$ exit

Passo 5 - Instalar o Composer

O Composer é uma ferramenta de gerenciamento de dependências para PHP e é necessária pelo Laravel, no qual o BookStack é baseado.

Baixe o script de instalação do Composer.

$ curl -sS https://getcomposer.org/installer -o composer-setup.php

Execute os seguintes comandos para verificar o instalador.

$ HASH=`curl -sS https://composer.github.io/installer.sig`
$ echo $HASH
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Instalador verificado'; } else { echo 'Instalador corrompido'; unlink('composer-setup.php'); } echo PHP_EOL;"

Os comandos acima pegam o valor do hash do instalador e o comparam com seu script baixado. Você deve ver a seguinte saída se o instalador estiver seguro para executar.

Instalador verificado

Instale o Composer.

$ sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Verifique a instalação verificando sua versão.

$ composer --version
Composer version 2.1.9 2021-10-05 09:47:38

Passo 6 - Baixar e Instalar o BookStack

Crie a pasta raiz para o aplicativo BookStack.

$ sudo mkdir -p /var/www/bookstack

Altere a propriedade do diretório /var/www/bookstack para o usuário atualmente logado.

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

Clone o branch de lançamento do repositório do BookStack no Github para a pasta recém-criada.

$ cd /var/www/bookstack
$ git clone https://github.com/BookStackApp/BookStack.git --branch=release --single-branch .

Não esqueça do ponto no final do comando clone. Isso garante que todos os arquivos sejam baixados no diretório atual em vez de criar um novo.

Execute o instalador do Composer a partir do diretório /var/www/bookstack.

$ composer install --no-dev

Copie o arquivo .env.example para .env para armazenar variáveis de ambiente para a instalação.

$ cp .env.example .env

Abra o arquivo para edição.

$ sudo nano .env

Preencha a URL do aplicativo e os detalhes do banco de dados. Se você for usar os recursos de email, preencha os detalhes SMTP ou então exclua-os do arquivo.

APP_URL=https://example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstackuser
DB_PASSWORD=bookstackpassword

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado ao terminar. Há muitas outras configurações que você pode configurar. Para saber mais sobre elas, abra o arquivo .env.example.complete e copie as que você precisa para o seu arquivo .env.

Gere uma chave de aplicativo única. Este valor é preenchido automaticamente no arquivo .env. Digite yes para prosseguir com o comando.

$ php artisan key:generate
**************************************
*     Aplicativo Em Produção!     *
************************************

 Você realmente deseja executar este comando? (sim/não) [não]:
 > sim

Chave do aplicativo definida com sucesso.

Atualize o Banco de Dados.

$ php artisan migrate
************************************
*     Aplicativo Em Produção!     *
**************************************

 Você realmente deseja executar este comando? (sim/não) [não]:
 > sim
Tabela de migração criada com sucesso.
Migrando: 2014_10_12_000000_create_users_table
Migrado:  2014_10_12_000000_create_users_table (0.12 segundos)
.......

Passo 7 - Instalar SSL do Let’s Encrypt

Para instalar um certificado SSL usando o Let’s Encrypt, precisamos instalar a ferramenta Certbot.

Usaremos o instalador de pacotes Snapd para isso. A maioria dos servidores Ubuntu não vem com a ferramenta Snap. Para corrigir isso, instale o Snap.

$ sudo apt install snapd

Certifique-se de que sua versão do Snapd está atualizada.

$ sudo snap install core 
$ sudo snap refresh core

Instale o Certbot.

$ sudo snap install --classic certbot

Use o seguinte comando para garantir que o comando Certbot possa ser executado criando um link simbólico para o diretório /usr/bin.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Verifique a instalação.

$ certbot --version
certbot 1.20.0

Gere o certificado SSL.

$ sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m [email protected] -d example.com

O comando acima fará o download de um certificado para o diretório /etc/letsencrypt/live/etherpad.example.com em seu servidor.

Gere um certificado de grupo Diffie-Hellman.

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Crie um diretório raiz de desafio para a renovação automática do Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Crie um Cron Job para renovar o SSL. Ele será executado todos os dias para verificar o certificado e renovar se necessário. Para isso, primeiro crie o arquivo /etc/cron.daily/certbot-renew e abra-o para edição.

$ sudo nano /etc/cron.daily/certbot-renew

Cole o seguinte código.

#!/bin/sh
certbot renew --cert-name bookstack.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

Altere as permissões do arquivo da tarefa para torná-lo executável.

$ sudo chmod +x /etc/cron.daily/certbot-renew

Passo 8 - Instalar e Configurar o Nginx

O Ubuntu vem com uma versão mais antiga do Nginx. Para instalar a versão mais recente, você precisa baixar o repositório oficial do Nginx.

Adicione o repositório para a versão estável do Nginx.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

Instale o Nginx.

$ sudo apt install nginx

Verifique a instalação.

$ nginx -v
nginx version: nginx/1.20.1

Habilite o serviço Nginx.

$ sudo systemctl enable nginx

Configurar PHP-FPM

Abra o arquivo /etc/php/7.4/fpm/pool.d/www.conf.

$ sudo nano /etc/php/7.4/fpm/pool.d/www.conf

Precisamos definir o usuário/grupo Unix dos processos PHP como nginx. Encontre as linhas user=www-data e group=www-data no arquivo e altere-as para nginx.

...
; Usuário/grupo Unix dos processos
; Nota: O usuário é obrigatório. Se o grupo não for definido, o grupo do usuário padrão
;       será usado.
user = nginx
group = nginx
...

Além disso, encontre as linhas listen.owner=www-data e listen.group=www-data no arquivo e altere-as para nginx.

listen.owner = nginx
listen.group = nginx

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

Reinicie o processo PHP-fpm.

$ sudo systemctl restart php7.4-fpm

Configurar Nginx

Crie e abra o arquivo /etc/nginx/conf.d/bookstack.conf para edição.

$ sudo nano /etc/nginx/conf.d/bookstack.conf

Cole o seguinte código nele.

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;
    server_name  bookstack.example.com;

    access_log  /var/log/nginx/bookstack.access.log;
    error_log   /var/log/nginx/bookstack.error.log;
    
    ssl_certificate      /etc/letsencrypt/live/bookstack.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/bookstack.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/bookstack.example.com/chain.pem;

    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

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

    location / {
      try_files $uri $uri/ /index.php?$query_string;
    }
  
    location ~ \.php$ {
      fastcgi_split_path_info ^(.+\.php)(/.+)$;
      include fastcgi_params;
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
      fastcgi_param PATH_INFO $fastcgi_path_info;
      fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    }
}

# forçar HTTPS
server {
    listen       80;
    listen       [::]:80;
    server_name  bookstack.example.com;
    return 301   https://$host$request_uri;
}

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado ao terminar.

Abra o arquivo /etc/nginx/nginx.conf para edição.

$ sudo nano /etc/nginx/nginx.conf

Adicione a seguinte linha antes da linha include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado. Valide o Nginx novamente.

Verifique a sintaxe do arquivo de configuração do Nginx.

$ sudo nginx -t
nginx: o arquivo de configuração /etc/nginx/nginx.conf a sintaxe está ok
nginx: arquivo de configuração /etc/nginx/nginx.conf teste bem-sucedido

Finalmente, inicie o serviço Nginx para habilitar a nova configuração.

$ sudo systemctl start nginx

Altere a propriedade do diretório para o usuário nginx para que o servidor web possa acessar e escrever na pasta.

$ sudo chown -R nginx:nginx /var/www/bookstack

Passo 9 - Executar o BookStack

Seu Bookstack está pronto para uso. Abra a URL https://bookstack.example.com em seu navegador e você verá a página de login.

Faça login usando a conta de administrador padrão [email protected] com a senha password. Abra a página Configurações >> Usuários e clique no botão ADICIONAR NOVO USUÁRIO.

Preencha os detalhes do usuário, marque a caixa Admin em Funções do Usuário e desmarque Enviar email de convite ao usuário já que não configuramos os detalhes SMTP. Selecione uma senha forte. Clique em Salvar quando terminar.

Em seguida, clique no usuário Admin padrão e exclua o usuário clicando no botão Excluir Usuário.

Transfira a propriedade do usuário Admin para o seu novo usuário criado selecionando-o no menu suspenso antes de excluí-lo. Clique em Confirmar para finalizar. Se você estiver logado com esse usuário, será desconectado automaticamente. Você precisará fazer login novamente com o usuário recém-criado.

Backup e restauração do BookStack

Backup do BookStack

Você precisa fazer backup do banco de dados e dos arquivos separadamente. Para fazer backup do banco de dados, use a ferramenta mysqldump.

$ sudo mysqldump -u bookstackuser bookstack > bookstack.backup.sql

Você também precisa fazer backup dos seguintes arquivos e pastas.

1. .env - arquivo contendo configurações importantes.
2. public/uploads - pasta contendo imagens carregadas.
3. storage/uploads - pasta contendo anexos de página carregados.

Execute o seguinte comando para criar um arquivo compactado dos arquivos e pastas acima.

$ sudo tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads

Restauração do BookStack

Execute o seguinte comando para restaurar o banco de dados.

$ sudo mysql -u bookstack < bookstack.backup.sql

Se você estiver restaurando para uma nova versão do BookStack, precisará executar o comando sudo php artisan migrate.

Para restaurar os arquivos compactados criados acima, use o seguinte comando.

$ sudo tar -xvzf bookstack-files-backup.tar.gz

Você também precisará alterar as permissões.

Atualizar o BookStack

Antes de atualizar o BookStack, certifique-se de fazer um backup adequado usando o processo mencionado anteriormente.

Para atualizar o BookStack, puxe os arquivos originais de seu repositório Git.

$ cd /var/www/bookstack
$ sudo git pull origin release

Execute os seguintes comandos para continuar a instalação.

$ sudo composer install --no-dev
$ sudo php artisan migrate

Você também precisará executar os seguintes comandos para limpar o cache.

$ sudo php artisan cache:clear
$ sudo php artisan config:clear
$ sudo php artisan view:clear

Conclusão

Isso conclui nosso tutorial sobre como instalar o BookStack em um servidor Ubuntu 20.04. Se você tiver alguma dúvida, poste nos comentários abaixo.