Cómo instalar BookStack con Nginx en Ubuntu 20.04

BookStack es una plataforma de código abierto, autoalojada y fácil de usar para organizar y almacenar información. Se puede utilizar para múltiples propósitos como un Wiki, sitio web de documentación y aplicación para tomar notas. Está construido utilizando el marco PHP Laravel y utiliza MySQL para almacenar los datos. Para fines de edición, te ofrece la opción de usar un editor WYSIWYG o un editor Markdown. Soporta autenticación multifactor y modo oscuro y es multilingüe.

Este tutorial te enseñará cómo instalar BookStack en un servidor basado en Ubuntu 20.04.

Prerrequisitos

1. Un servidor que ejecute Ubuntu 20.04
2. Un Nombre de Dominio Totalmente Calificado (FQDN) apuntando hacia el servidor.
3. Un usuario no root con privilegios sudo.
4. Versión de PHP 7.3 o mayor.
5. MySQL>=5.6 y MariaDB>=10.0
6. Git y Composer.

Paso 1 - Configurar el Firewall

El primer paso es configurar el firewall. Ubuntu viene con ufw (Uncomplicated Firewall) por defecto.

Verifica si el firewall está en ejecución.

$ sudo ufw status

Deberías obtener la siguiente salida.

Status: inactive

Permite el puerto SSH para que el firewall no interrumpa la conexión actual al habilitarlo.

$ sudo ufw allow OpenSSH

Permite también los puertos HTTP y HTTPS.

$ sudo ufw allow 80
$ sudo ufw allow 443

Habilita el Firewall

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Verifica el estado del firewall nuevamente.

$ sudo ufw status

Deberías ver una salida similar.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Paso 2 - Instalar Git

El primer paso es instalar Git. Será necesario para descargar y actualizar BookStack. Ejecuta el siguiente comando para instalar Git.

$ sudo apt install git

Verifica la instalación.

$ git --version

Paso 3 - Instalar PHP y extensiones

Dado que BookStack depende de PHP, necesitas instalar PHP y sus extensiones.

Ubuntu viene con una versión de PHP desactualizada. Primero, necesitamos agregar el repositorio de PHP de Ondrej.

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

A continuación, instala PHP y sus extensiones requeridas por 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

Verifica la instalación.

$ 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

Paso 4 - Instalar y Configurar MariaDB

Ubuntu viene con una versión más antigua de MariaDB. Para instalar la última versión, agrega el repositorio oficial de MariaDB. Ejecuta los siguientes comandos para agregar el repositorio.

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

Ejecuta el siguiente comando para instalar el servidor MariaDB.

$ sudo apt install mariadb-server

Asegura la instalación de MariaDB.

$ sudo mysql_secure_installation

Te enfrentarás a varios mensajes. Respóndelos de la siguiente manera.

Enter current password for root (enter for none): Presiona Enter
Switch to unix_socket authentication [Y/n] Escribe y
Change the root password? [Y/n] Escribe n
Remove anonymous users? [Y/n] Escribe y
Disallow root login remotely? [Y/n] Escribe y
Remove test database and access to it? [Y/n] Escribe y
Reload privilege tables now? [Y/n] Escribe y

Conéctate a la shell de MariaDB usando el siguiente comando.

$ sudo mysql

Crea una nueva base de datos para Bookstack.

$ create database bookstack;

Crea un nuevo usuario de base de datos.

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

Elige una contraseña fuerte.

Otorga permisos en la base de datos al usuario.

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

Sal de la shell de MySQL.

$ exit

Paso 5 - Instalar Composer

Composer es una herramienta de gestión de dependencias para PHP y es requerida por Laravel en el que se basa BookStack.

Descarga el script instalador de Composer.

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

Ejecuta los siguientes comandos para verificar el instalador.

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

Los comandos anteriores obtienen el valor hash del instalador y lo comparan con tu script descargado. Deberías ver la siguiente salida si el instalador es seguro para ejecutar.

Installer verified

Instala Composer.

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

Verifica la instalación comprobando su versión.

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

Paso 6 - Descargar e Instalar BookStack

Crea la carpeta raíz para la aplicación BookStack.

$ sudo mkdir -p /var/www/bookstack

Cambia la propiedad del directorio /var/www/bookstack al usuario que ha iniciado sesión actualmente.

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

Clona la rama de lanzamiento del repositorio de Github de BookStack en la carpeta recién creada.

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

No te olvides del punto al final del comando clone. Asegura que todos los archivos se descarguen en el directorio actual en lugar de crear uno nuevo.

Ejecuta el instalador de Composer desde el directorio /var/www/bookstack.

$ composer install --no-dev

Copia el archivo .env.example a .env para almacenar las variables de entorno para la instalación.

$ cp .env.example .env

Abre el archivo para editar.

$ sudo nano .env

Completa la URL de la aplicación y los detalles de la base de datos. Si vas a usar las funciones de correo electrónico, completa los detalles de SMTP o elimínalos del archivo.

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

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida una vez que hayas terminado. Hay muchos más ajustes que puedes configurar. Para saber más sobre ellos, abre el archivo .env.example.complete y copia los que necesites a tu archivo .env.

Genera una clave de aplicación única. Este valor se llena automáticamente en el archivo .env. Escribe yes para continuar con el comando.

$ php artisan key:generate
**************************************
*     Application In Production!     *
************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes

Application key set successfully.

Actualiza la base de datos.

$ php artisan migrate
************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes
Migration table created successfully.
Migrating: 2014_10_12_000000_create_users_table
Migrated:  2014_10_12_000000_create_users_table (0.12 seconds)
.......

Paso 7 - Instalar SSL de Let’s Encrypt

Para instalar un certificado SSL usando Let’s Encrypt, necesitamos instalar la herramienta Certbot.

Usaremos el instalador de paquetes Snapd para eso. La mayoría de los servidores Ubuntu no vienen con la herramienta Snap. Para solucionar eso, instala Snap.

$ sudo apt install snapd

Asegúrate de que tu versión de Snapd esté actualizada.

$ sudo snap install core 
$ sudo snap refresh core

Instala Certbot.

$ sudo snap install --classic certbot

Usa el siguiente comando para asegurarte de que el comando Certbot pueda ejecutarse creando un enlace simbólico al directorio /usr/bin.

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

Verifica la instalación.

$ certbot --version
certbot 1.20.0

Genera el certificado SSL.

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

El comando anterior descargará un certificado en el directorio /etc/letsencrypt/live/etherpad.example.com en tu servidor.

Genera un certificado de grupo Diffie-Hellman.

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

Crea un directorio raíz web de desafío para la renovación automática de Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Crea un trabajo Cron para renovar el SSL. Se ejecutará todos los días para verificar el certificado y renovarlo si es necesario. Para eso, primero crea el archivo /etc/cron.daily/certbot-renew y ábrelo para editar.

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

Pega el siguiente código.

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

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

Cambia los permisos en el archivo de tarea para hacerlo ejecutable.

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

Paso 8 - Instalar y Configurar Nginx

Ubuntu viene con una versión más antigua de Nginx. Para instalar la última versión, necesitas descargar el repositorio oficial de Nginx.

Agrega el repositorio para la versión estable de 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

Instala Nginx.

$ sudo apt install nginx

Verifica la instalación.

$ nginx -v
nginx version: nginx/1.20.1

Habilita el servicio Nginx.

$ sudo systemctl enable nginx

Configurar PHP-FPM

Abre el archivo /etc/php/7.4/fpm/pool.d/www.conf.

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

Necesitamos establecer el usuario/grupo Unix de los procesos PHP a nginx. Encuentra las líneas user=www-data y group=www-data en el archivo y cámbialas a nginx.

...
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = nginx
group = nginx
...

Además, encuentra las líneas listen.owner=www-data y listen.group=www-data en el archivo y cámbialas a nginx.

listen.owner = nginx
listen.group = nginx

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

Reinicia el proceso PHP-fpm.

$ sudo systemctl restart php7.4-fpm

Configurar Nginx

Crea y abre el archivo /etc/nginx/conf.d/bookstack.conf para editar.

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

Pega el siguiente código en él.

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;
    }
}

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

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida una vez que hayas terminado.

Abre el archivo /etc/nginx/nginx.conf para editar.

$ sudo nano /etc/nginx/nginx.conf

Agrega la siguiente línea antes de la línea include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida. Valida Nginx nuevamente.

Verifica la sintaxis del archivo de configuración de Nginx.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Finalmente, inicia el servicio Nginx para habilitar la nueva configuración.

$ sudo systemctl start nginx

Cambia la propiedad del directorio al usuario nginx para que el servidor web pueda acceder y escribir en la carpeta.

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

Paso 9 - Ejecutar BookStack

Tu Bookstack está listo para usar. Abre la URL https://bookstack.example.com en tu navegador y verás la página de inicio de sesión.

Inicia sesión usando la cuenta de administrador predeterminada [email protected] con una contraseña de password. Abre la página Configuraciones >> Usuarios y haz clic en el botón AGREGAR NUEVO USUARIO.

Completa los detalles del usuario, marca la casilla Admin bajo Roles de Usuario y desmarca Enviar correo de invitación al usuario ya que no configuramos los detalles de SMTP. Selecciona una contraseña fuerte. Haz clic en Guardar cuando termines.

A continuación, haz clic en el usuario Admin predeterminado y elimina al usuario haciendo clic en el botón Eliminar Usuario.

Transfiere la propiedad del usuario Admin a tu nuevo usuario creado seleccionándolo del menú desplegable antes de eliminarlo. Haz clic en Confirmar para finalizar. Si has iniciado sesión con ese usuario, serás desconectado automáticamente. Necesitarás iniciar sesión nuevamente con el nuevo usuario creado.

Respaldo y restauración de BookStack

Respaldo de BookStack

Necesitas respaldar la base de datos y los archivos por separado. Para respaldar la base de datos, usa la herramienta mysqldump.

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

También necesitas respaldar los siguientes archivos y carpetas.

1. .env - archivo que contiene la configuración importante.
2. public/uploads - carpeta que contiene imágenes subidas.
3. storage/uploads - carpeta que contiene archivos adjuntos de página subidos.

Ejecuta el siguiente comando para crear un archivo comprimido de los archivos y carpetas anteriores.

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

Restaurar BookStack

Ejecuta el siguiente comando para restaurar la base de datos.

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

Si estás restaurando a una nueva versión de BookStack, tendrás que ejecutar el comando sudo php artisan migrate.

Para restaurar los archivos comprimidos creados anteriormente, usa el siguiente comando.

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

También necesitarás cambiar los permisos.

Actualizar BookStack

Antes de actualizar BookStack, asegúrate de hacer un respaldo adecuado utilizando el proceso mencionado anteriormente.

Para actualizar BookStack, extrae los archivos originales de su repositorio Git.

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

Ejecuta los siguientes comandos para continuar con la instalación.

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

También necesitarás ejecutar los siguientes comandos para limpiar la caché.

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

Conclusión

Esto concluye nuestro tutorial sobre la instalación de BookStack en un servidor Ubuntu 20.04. Si tienes alguna pregunta, publícalas en los comentarios a continuación.