Cómo instalar BookStack en Ubuntu 24.04 con Nginx y MySQL

BookStack es una plataforma de documentación de código abierto, escrita en PHP con Laravel, que organiza el contenido en estanterías, libros, capítulos y páginas. En este tutorial instalarás BookStack en Ubuntu 24.04 con PHP 8.3, MySQL 8 y Nginx, lo publicarás con HTTPS mediante Let's Encrypt y dejarás programada una copia de seguridad diaria de la base de datos y los archivos subidos.

Requisitos previos

Para seguir esta guía necesitas:

Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 1 GB de RAM (2 GB recomendados) y 10 GB libres en disco.
Un usuario no root con privilegios sudo.
Un dominio o subdominio con un registro DNS A apuntando a la IP del servidor. En esta guía se usa your_domain como marcador; sustitúyelo por el tuyo.
Los puertos 22, 80 y 443 abiertos.

Paso 1: Instalar Nginx, PHP y MySQL

BookStack necesita PHP 8.2 o superior con varias extensiones, un servidor web y una base de datos MySQL o MariaDB. Ubuntu 24.04 incluye PHP 8.3 en sus repositorios, así que no hace falta añadir repositorios externos.

Actualiza el índice de paquetes e instala todo lo necesario:

sudo apt update
sudo apt install nginx mysql-server git unzip composer php-fpm php-curl php-mbstring php-ldap php-xml php-zip php-gd php-mysql

Comprueba que PHP-FPM está en marcha:

systemctl status php8.3-fpm --no-pager

● php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php8.3-fpm.service; enabled; preset: enabled)
     Active: active (running)

Permite el tráfico HTTP y HTTPS en el cortafuegos si usas UFW:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Paso 2: Crear la base de datos

Ejecuta el asistente de seguridad de MySQL para eliminar usuarios anónimos y la base de datos de prueba. Puedes responder Y a todas las preguntas:

sudo mysql_secure_installation

Abre la consola de MySQL. En Ubuntu el usuario root de MySQL se autentica por socket, así que no pide contraseña al usar sudo:

sudo mysql

Crea la base de datos y un usuario exclusivo para BookStack. Sustituye your_strong_password por una contraseña robusta:

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

Verifica que el nuevo usuario puede conectarse:

mysql -u bookstack -p -e "SHOW DATABASES;"

+--------------------+
| Database           |
+--------------------+
| bookstack          |
| information_schema |
| performance_schema |
+--------------------+

Paso 3: Descargar BookStack e instalar sus dependencias

El proyecto publica cada versión estable en la rama release de su repositorio. Clonar esa rama facilita las actualizaciones posteriores, que se reducen a un git pull:

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

Instala las dependencias de PHP con Composer. La variable COMPOSER_ALLOW_SUPERUSER evita el aviso por ejecutarlo como root; más adelante cambiarás el propietario de los archivos:

cd /var/www/bookstack
sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --no-interaction

Al terminar, el directorio vendor/ contendrá las librerías de Laravel:

ls /var/www/bookstack/vendor | head -3

autoload.php
bacon
barryvdh

Paso 4: Configurar el entorno de BookStack

La configuración de BookStack se guarda en el archivo .env. Crea una copia a partir de la plantilla:

sudo cp .env.example .env
sudo nano .env

Ajusta la URL pública y los datos de la base de datos creada en el paso 2:

APP_URL=https://your_domain

DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=your_strong_password

APP_URL debe coincidir exactamente con la dirección que usarán los navegadores, incluido https:// y sin barra final; si no coincide, los enlaces y las imágenes se generarán mal.

Genera la clave de cifrado de la aplicación:

sudo php artisan key:generate --no-interaction --force

   INFO  Application key set successfully.

Asigna los archivos al usuario del servidor web y restringe los permisos de .env, que contiene la contraseña de la base de datos:

sudo chown -R www-data:www-data /var/www/bookstack
sudo chmod 640 /var/www/bookstack/.env

Crea las tablas ejecutando las migraciones como www-data, para que los archivos de caché y de log que se generen tengan el propietario correcto:

sudo -u www-data php artisan migrate --force

La salida lista cada migración con DONE. Si ves un error SQLSTATE[HY000] [1045] Access denied, revisa DB_USERNAME y DB_PASSWORD en .env.

Paso 5: Configurar Nginx

Crea un bloque de servidor para BookStack. La raíz debe ser el directorio public/, nunca la raíz del proyecto, para no exponer .env ni el código:

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

server {
    listen 80;
    listen [::]:80;
    server_name your_domain;

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

    client_max_body_size 50M;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ /\.(?!well-known) {
        deny all;
    }
}

Activa el sitio, desactiva el sitio por defecto y comprueba la sintaxis:

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

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Recarga Nginx:

sudo systemctl reload nginx

El valor client_max_body_size 50M permite subir adjuntos de hasta 50 MB. PHP también limita el tamaño de subida; para igualarlo, edita /etc/php/8.3/fpm/php.ini, pon upload_max_filesize = 50M y post_max_size = 50M, y reinicia PHP-FPM con sudo systemctl restart php8.3-fpm.

Paso 6: Activar HTTPS con Let's Encrypt

Instala Certbot y su plugin para Nginx:

sudo apt install certbot python3-certbot-nginx

Solicita el certificado. Certbot añadirá la configuración TLS al bloque de servidor y la redirección de HTTP a HTTPS:

sudo certbot --nginx -d your_domain

El paquete de Ubuntu instala un temporizador de systemd que renueva los certificados automáticamente. Comprueba que la renovación funciona:

sudo certbot renew --dry-run

Congratulations, all simulated renewals succeeded:
  /etc/letsencrypt/live/your_domain/fullchain.pem (success)

Verifica que BookStack responde por HTTPS y redirige a la pantalla de acceso:

curl -sI https://your_domain | grep -i -E '^(HTTP|location)'

HTTP/1.1 302 Found
location: https://your_domain/login

Paso 7: Acceder y cambiar la cuenta de administrador

Abre https://your_domain en el navegador. BookStack crea un administrador por defecto con estas credenciales:

Correo: [email protected]
Contraseña: password

Inicia sesión y, de inmediato, entra en el icono de tu usuario, Editar perfil, y cambia el nombre, el correo y la contraseña. Mientras no lo hagas, cualquiera que conozca las credenciales por defecto puede entrar.

Después revisa Ajustes para definir el nombre de la aplicación, el idioma por defecto y si quieres permitir el acceso público de solo lectura. Para enviar invitaciones y restablecer contraseñas por correo, configura las variables MAIL_* de .env con los datos de tu servidor SMTP.

Paso 8: Programar copias de seguridad

Una copia completa de BookStack consiste en la base de datos más los archivos subidos (public/uploads, storage/uploads), los temas (themes) y el archivo .env. Crea un script que guarde todo ello y elimine las copias de más de 14 días:

sudo nano /usr/local/bin/bookstack-backup

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/var/backups/bookstack"
APP_DIR="/var/www/bookstack"
STAMP="$(date +%F_%H%M)"

mkdir -p "$BACKUP_DIR"
chmod 700 "$BACKUP_DIR"

mysqldump --single-transaction bookstack | gzip > "$BACKUP_DIR/bookstack-db-$STAMP.sql.gz"
tar -czf "$BACKUP_DIR/bookstack-files-$STAMP.tar.gz" -C "$APP_DIR" .env public/uploads storage/uploads themes

find "$BACKUP_DIR" -type f -mtime +14 -delete

El script se ejecuta como root, que accede a MySQL por socket sin necesidad de guardar contraseñas en el archivo. Hazlo ejecutable y pruébalo:

sudo chmod 750 /usr/local/bin/bookstack-backup
sudo /usr/local/bin/bookstack-backup
sudo ls -lh /var/backups/bookstack

-rw-r--r-- 1 root root 48K Sep 25 10:12 bookstack-db-2026-09-25_1012.sql.gz
-rw-r--r-- 1 root root 12K Sep 25 10:12 bookstack-files-2026-09-25_1012.tar.gz

Prográmalo cada noche a las 02:30 con un archivo en /etc/cron.d:

echo '30 2 * * * root /usr/local/bin/bookstack-backup' | sudo tee /etc/cron.d/bookstack-backup

Copia estos archivos periódicamente fuera del servidor; una copia que vive en el mismo disco no te protege si pierdes el servidor.

Actualizar BookStack

Antes de actualizar, lanza una copia de seguridad y lee las notas de la versión en GitHub. Después descarga la nueva versión, reinstala las dependencias y aplica las migraciones:

cd /var/www/bookstack
sudo /usr/local/bin/bookstack-backup
sudo git -c safe.directory=/var/www/bookstack pull origin release
sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --no-interaction
sudo chown -R www-data:www-data /var/www/bookstack
sudo -u www-data php artisan migrate --force

Limpia las cachés para que se carguen las vistas y la configuración nuevas:

sudo -u www-data php artisan cache:clear
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan view:clear

Solución de problemas

Error 500 tras la instalación: revisa /var/www/bookstack/storage/logs/laravel.log. La causa más habitual son permisos; vuelve a ejecutar sudo chown -R www-data:www-data /var/www/bookstack.
Las imágenes no cargan o los enlaces apuntan a http://: APP_URL en .env no coincide con la URL real. Corrígelo y ejecuta sudo -u www-data php artisan config:clear.
Error 413 al subir archivos: aumenta client_max_body_size en Nginx y upload_max_filesize y post_max_size en php.ini.
502 Bad Gateway: PHP-FPM no está en marcha o la ruta del socket es distinta. Comprueba systemctl status php8.3-fpm y que existe /run/php/php8.3-fpm.sock.

Conclusión

Tienes BookStack funcionando en Ubuntu 24.04 detrás de Nginx con HTTPS, con la cuenta de administrador protegida y copias de seguridad diarias. Como siguientes pasos, puedes crear roles y permisos por libro para tu equipo, conectar el inicio de sesión a LDAP o a un proveedor SAML/OIDC siguiendo la documentación oficial de BookStack, y enviar las copias a un almacenamiento externo.

On this page