Cómo instalar BookStack con Nginx en Ubuntu 20.04
BookStack es una plataforma autoalojada, de código abierto y fácil de usar para organizar y almacenar información. Puede utilizarse para múltiples propósitos, como una Wiki, un sitio web de documentación y una aplicación para tomar notas. Está construida con el framework PHP Laravel y utiliza MySQL para almacenar los datos. Para la edición, puedes elegir entre utilizar un editor WYSIWYG o Markdown. Admite autenticación multifactor y modo oscuro, y es multilingüe.
Este tutorial te enseñará a instalar BookStack en un servidor basado en Ubuntu 20.04.
Requisitos previos
- Un servidor con Ubuntu 20.04
- Un Nombre de Dominio Completamente Cualificado (FQDN) apuntando hacia el servidor.
- Un usuario no root con privilegios sudo.
- PHP versión 7.3 o superior.
- MySQL>=5.6 y MariaDB>=10.0
- Git y Composer.
Paso 1 – Configurar el cortafuegos
El primer paso es configurar el cortafuegos. Ubuntu viene con ufw (Uncomplicated Firewall) por defecto.
Comprueba si el cortafuegos se está ejecutando.
$ sudo ufw status
Deberías obtener la siguiente salida.
Status: inactive
Permite el puerto SSH para que el cortafuegos no rompa la conexión actual al activarlo.
$ sudo ufw allow OpenSSH
Permite también los puertos HTTP y HTTPS.
$ sudo ufw allow 80 $ sudo ufw allow 443
Habilita el cortafuegos
$ sudo ufw enable Command may disrupt existing ssh connections. Proceed with operation (y|n)? y Firewall is active and enabled on system startup
Comprueba de nuevo el estado del cortafuegos.
$ sudo ufw status
Deberías ver un resultado 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
Como BookStack depende de PHP, necesitas instalar PHP y sus extensiones.
Ubuntu se entrega con una versión obsoleta de PHP. Primero, tenemos que añadir el repositorio PHP de Ondrej.
$ sudo add-apt-repository ppa:ondrej/php
A continuación, instala PHP y sus extensiones, necesarias para 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 incluye una versión antigua de MariaDB. Para instalar la última versión, añade el repositorio oficial de MariaDB. Ejecuta los siguientes comandos para añadir 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 aparecerán varias preguntas. Respóndelas como se indica a continuación.
Enter current password for root (enter for none): Press Enter Switch to unix_socket authentication [Y/n] Type y Change the root password? [Y/n] Type n Remove anonymous users? [Y/n] Type y Disallow root login remotely? [Y/n] Type y Remove test database and access to it? [Y/n] Type y Reload privilege tables now? [Y/n] Type y
Conéctate al shell de MariaDB utilizando 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 segura.
Concede permisos sobre la base de datos al usuario.
$ grant CREATE,ALTER,SELECT,INSERT,UPDATE,DELETE on `bookstack`.* to 'bookstackuser'@'localhost';
Sal del intérprete de comandos MySQL.
$ exit
Paso 5 – Instalar Composer
Composer es una herramienta de gestión de dependencias para PHP y es necesaria para 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 es seguro ejecutar el instalador.
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 – Descarga e instala 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 actualmente conectado.
$ sudo chown -R $USER:$USER /var/www/bookstack
Clona la rama de lanzamiento del repositorio BookStack de Github en la carpeta recién creada.
$ cd /var/www/bookstack $ git clone https://github.com/BookStackApp/BookStack.git --branch=release --single-branch .
No te pierdas el dot al final del comando clone. Garantiza 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 en .env para almacenar variables de entorno para la instalación.
$ cp .env.example .env
Abre el archivo para editarlo.
$ sudo nano .env
Rellena la URL de la aplicación y los detalles de la base de datos. Si vas a utilizar las funciones de correo electrónico, introduce los datos 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 pulsando Ctrl + X e introduciendo Y cuando se te pida una vez 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 en tu archivo .env.
Genera una clave de aplicación única. Este valor se rellena automáticamente en el archivo .env. Escribe yes para proceder 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 Let’s Encrypt SSL
Para instalar un certificado SSL utilizando Let’s Encrypt, necesitamos instalar la herramienta Certbot.
Para ello utilizaremos el instalador de paquetes Snapd. La mayoría de los servidores Ubuntu no incluyen la herramienta Snap. Para solucionarlo, 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
Utiliza el siguiente comando para asegurarte de que se puede ejecutar el comando Certbot 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 de 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 Cron Job para renovar el SSL. Se ejecutará cada día para comprobar el certificado y renovarlo si es necesario. Para ello, primero, crea el archivo /etc/cron.daily/certbot-renew y ábrelo para editarlo.
$ 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 pulsando Ctrl + X e introduciendo Y cuando te lo pida.
Cambia los permisos del archivo de tareas para que sea ejecutable.
$ sudo chmod +x /etc/cron.daily/certbot-renew
Paso 8 – Instalar y configurar Nginx
Ubuntu incluye una versión antigua de Nginx. Para instalar la última versión, necesitas descargar el repositorio oficial de Nginx.
Añade el repositorio de 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. Busca las líneas user=www-data y group=www-data en el archivo y cámbialas por 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 ...
Busca también las líneas listen.owner=www-data y listen.group=www-data en el archivo y cámbialas por nginx.
listen.owner = nginx listen.group = nginx
Guarda el archivo pulsando Ctrl + X e introduciendo Y cuando se te solicite.
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 editarlo.
$ sudo nano /etc/nginx/conf.d/bookstack.conf
Pega en él el siguiente código.
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 pulsando Ctrl + X e introduciendo Y cuando se te solicite una vez hayas terminado.
Abre el archivo /etc/nginx/nginx.conf para editarlo.
$ sudo nano /etc/nginx/nginx.conf
Añade la siguiente línea antes de la línea include /etc/nginx/conf.d/*.conf;.
server_names_hash_bucket_size 64;
Guarda el archivo pulsando Ctrl + X e introduciendo Y cuando se te solicite. Vuelve a validar Nginx.
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
Por último, 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 a la carpeta y escribir en ella.
$ sudo chown -R nginx:nginx /var/www/bookstack
Paso 9 – Ejecuta BookStack
Tu Bookstack está listo para ser utilizado. Abre la URL https://bookstack.example.com en tu navegador y obtendrás la página de inicio de sesión.
Inicia sesión utilizando la cuenta de administrador por defecto [email protected] con la contraseña password. Abre la página Configuración >> Usuarios y haz clic en el botón AÑADIR NUEVO USUARIO.
Rellena los datos del usuario, marca la casilla Admin en Roles de usuario y desmarca Enviar correo electrónico de invitación al usuario, ya que no hemos configurado los datos SMTP. Selecciona una contraseña segura. Haz clic en Guardar cuando hayas terminado.
A continuación, haz clic en el usuario Admin por defecto y elimínalo haciendo clic en el botón Eliminar usuario.
Transfiere la propiedad del usuario Admin a tu usuario recién creado seleccionándolo en el menú desplegable antes de eliminarlo. Haz clic en Confirmar para finalizar. Si has iniciado sesión con ese usuario, se cerrará automáticamente la sesión. Tendrás que volver a iniciar sesión con el usuario recién creado.
Copia de seguridad y restauración de BookStack
Copia de seguridad de BookStack
Tienes que hacer una copia de seguridad de la base de datos y de los archivos por separado. Para hacer una copia de seguridad de la base de datos, utiliza la herramienta mysqldump.
$ sudo mysqldump -u bookstackuser bookstack > bookstack.backup.sql
También necesitas hacer una copia de seguridad de los siguientes archivos y carpetas.
.env– archivo que contiene la configuración importante.public/uploads– carpeta que contiene imágenes subidas.storage/uploads– carpeta que contiene los archivos adjuntos de las páginas subidas.
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, utiliza el siguiente comando.
$ sudo tar -xvzf bookstack-files-backup.tar.gz
También tendrás que cambiar los permisos.
Actualizar BookStack
Antes de actualizar BookStack, asegúrate de hacer una copia de seguridad adecuada 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 la instalación.
$ sudo composer install --no-dev $ sudo php artisan migrate
También tendrás que ejecutar los siguientes comandos para borrar la caché.
$ sudo php artisan cache:clear $ sudo php artisan config:clear $ sudo php artisan view:clear
Conclusión
Con esto concluye nuestro tutorial sobre la instalación de BookStack en un servidor Ubuntu 20.04. Si tienes alguna pregunta, publícala en los comentarios a continuación.