Alojar BookStack en un VPS administrado: su documentación en su casa

Qué hace BookStack

BookStack es una plataforma de documentación pensada para seguir siendo sencilla: su README busca una toma de contacto inmediata, con unas simples nociones de procesador de textos. Sus equipos escriben en ella sus procedimientos, su documentación y su base de conocimiento, en un navegador, en español si lo desean.

• Cuatro niveles de organización: las estanterías agrupan libros, los libros contienen capítulos y páginas, los capítulos son opcionales, y el contenido vive en las páginas.
• Dos editores: un editor visual por defecto y un editor Markdown con vista previa en directo, a los que se añaden los esquemas de diagrams.net.
• La búsqueda: dentro de un libro, o en el conjunto de libros, capítulos y páginas.
• Los permisos: roles para todo el sistema y permisos propios de una estantería, un libro, un capítulo o una página.
• Los inicios de sesión: correo y contraseña, OpenID Connect, SAML 2.0, LDAP, con una doble autenticación mediante aplicación o códigos de respaldo, que puede imponerse por rol.
• El seguimiento y los intercambios: el historial de revisiones de cada página, una API REST y la exportación a HTML, PDF, texto, Markdown o ZIP portátil.

El proyecto asume sus decisiones: su README precisa que BookStack no está concebido como una plataforma extensible hacia otros usos, y sigue centrado en la documentación. Su renderizado de PDF pasa por dompdf, sin instalar nada más, con capacidades limitadas; el proyecto documenta otros motores con EXPORT_PDF_COMMAND.

Lo que permite la licencia MIT

BookStack se publica bajo la licencia MIT por Dan Brown y los colaboradores del proyecto. Autoriza cualquier uso, cualquier modificación y cualquier distribución, con una condición: conservar el aviso de copyright y el texto de la licencia en toda copia del software. Las preguntas frecuentes del proyecto precisan que esta atribución se refiere al código que usted comparte: nada le obliga a mostrar el nombre o el logotipo de BookStack en su instancia.

El proyecto mantiene una sola versión, libre y gratuita: no ofrece edición empresarial, y no tiene alojamiento oficial ni proyecto de abrir uno. En cambio, vende planes de soporte, que contribuyen a su financiación junto con las donaciones y los patrocinios. BookStack se instala, por tanto, en su servidor, sin ninguna licencia que comprar.

Los requisitos de BookStack

Docker sigue siendo opcional. El proyecto no publica una imagen oficial: las instalaciones en contenedor proceden de proyectos de la comunidad, LinuxServer.io y solidnerd. Esta guía sigue la vía oficial, PHP y MySQL directamente en el servidor, que no exige nada más.

La documentación descarta el alojamiento PHP compartido: BookStack requiere un servidor que usted administre. No cifra ni la memoria ni el procesador necesarios. En un VPS administrado, descríbanos su uso, el número de personas y el volumen de imágenes y de archivos adjuntos, y le recomendamos el tamaño adecuado.

La instalación de BookStack

El proyecto propone dos vías: un script para Ubuntu, el más corto en un servidor nuevo, y una instalación manual para todos los demás casos.

Con el script del proyecto, en un Ubuntu recién instalado

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

Estos scripts están reservados a un sistema recién instalado: pueden sobrescribir una configuración web existente. Dejan también de lado dos asuntos, los ajustes de correo y la seguridad del sistema, que hay que prever aparte.

El script coloca BookStack en /var/www/bookstack. El de Ubuntu 26.04 pide el dominio y la dirección de la cuenta de administrador, y muestra al final una contraseña generada al azar, que no figura en su registro: anótela. Con otro script, tome nota de los accesos que se muestran al final y cambie cualquier acceso por defecto desde el primer inicio de sesión.

A mano, en cualquier otra máquina

Empiece por la base de datos: una base y un usuario limitado a esa base. El script del proyecto procede así, con la contraseña que usted elija en lugar de change-me:

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

Descargue después la rama release, aplique los permisos que da la documentación para /var/www/bookstack e instale las dependencias:

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER: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
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Indique la base y la dirección en .env:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Apunte por último la raíz web a la carpeta public: DocumentRoot en Apache, root en Nginx. Sin Apache, o cuando los archivos .htaccess están desactivados, añada las reglas de reescritura de direcciones: el proyecto publica ejemplos para Apache y para Nginx.

Una instalación manual se abre con la cuenta admin@admin.com y la contraseña password. Cambie la dirección y la contraseña desde el primer inicio de sesión.

HTTPS y APP_URL

Los visitantes llegan por los puertos 80 y 443, bajo el nombre de dominio del servidor. Cree para ese nombre registros A y AAAA y solicite después el certificado: el script de Ubuntu 26.04 configura Apache solo en el puerto 80, y la página de instalación deja HTTPS en sus manos. Certbot instala el certificado Let’s Encrypt, adapta Apache y renueva el certificado por sí mismo. Con Nginx, sustituya --apache por --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Pase después la dirección a HTTPS en .env. APP_URL debe corresponder exactamente a la dirección de visita, prefijo incluido: una discrepancia se nota por estilos ausentes, iconos desmesurados y menús rotos. Una dirección en https activa por sí misma las cookies seguras.

APP_URL=https://docs.example.com

Si ya existen páginas, sus enlaces conservan la dirección antigua en la base. Haga copia de la base y ejecute después el comando del proyecto:

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

BookStack se sirve en la raíz de un dominio o de un subdominio, y la documentación describe también una instalación en una subcarpeta, como example.com/bookstack. Si se añade un proxy inverso delante de Apache, declare su dirección en APP_PROXIES: sin ella, el registro de auditoría y la limitación de caudal ven la dirección del proxy en lugar de la de los visitantes. La documentación reserva APP_PROXIES="*" para el diagnóstico.

Dónde viven sus datos

Conserve la misma APP_KEY a lo largo del tiempo y haga copia de ella. BookStack la usa para cifrar, entre otras cosas, los secretos de doble autenticación: cambiarla puede romper esas funciones, y desde la versión 26.09 la aplicación devuelve un error si falta.

Las imágenes son públicas por defecto

Con el almacenamiento por defecto, el servidor web sirve directamente las imágenes, lo que es rápido, y cualquier persona que conozca su dirección puede abrirlas. Para una documentación interna, la elección se hace en STORAGE_TYPE:

Para los archivos pesados, hay que ajustar tres valores a la vez: FILE_UPLOAD_SIZE_LIMIT en .env, post_max_size y upload_max_filesize en php.ini, y client_max_body_size en Nginx, que vale 1 MB por defecto.

Otros dos ajustes cuentan también para una documentación viva: cada página conserva 100 revisiones por defecto (REVISION_LIMIT), y la papelera guarda los elementos eliminados durante 30 días (RECYCLE_BIN_LIFETIME).

Los correos: SMTP y cola de espera

BookStack envía correos para la confirmación de las direcciones, el olvido de contraseña, las invitaciones y las notificaciones. Desde un VPS de Simafri, el envío pasa por un relé SMTP autenticado, en el puerto 587: la dirección de una cuenta de correo que ya tenga, o Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Compruebe el resultado en «Settings», «Maintenance», con la acción «Send a Test Email», que muestra los errores encontrados. Un fallo durante una invitación se muestra en pantalla, mientras que un fallo de notificación queda en el registro de la aplicación.

Enviar en segundo plano

Por defecto, BookStack envía correos y webhooks durante la petición, lo que puede ralentizar las páginas. Para pasar a segundo plano, escriba QUEUE_CONNECTION=database en .env y ponga en marcha un servicio, con el ejemplo que da la documentación para una instalación Ubuntu por script:

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Proteger su instancia de BookStack

La documentación de seguridad da una lista que conviene repasar desde la instalación:

1. Cambie la dirección y la contraseña del primer administrador.
2. Compruebe que el servidor web sirve solo la carpeta public, sobre todo si BookStack vive en /var/www.
3. Limite el usuario de la base a la única base de BookStack.
4. Indique APP_URL, para que las direcciones generadas por el sistema no puedan manipularse.
5. Revise los ajustes de registro y de acceso público, y después los roles.

La doble autenticación se impone después por rol. Suscríbase también a la lista de distribución de seguridad del proyecto, para recibir sus alertas. La dirección /status sirve para una supervisión: responde 200 cuando todo va bien, y un código de error igual o superior a 400 en caso contrario.

PHP cuenta tanto como BookStack. El proyecto publicó el 21 de octubre de 2026 una alerta sobre una actualización crítica de PHP, corregida en 8.5.12, 8.4.27, 8.3.36 y 8.2.35. Ubuntu publica esas correcciones con sus propios números de paquete, como 8.3.6-0ubuntu0.24.04.13 para Ubuntu 24.04.

Para sus contenidos, mantenga activado el filtrado por defecto, y reserve su relajación para las instancias donde solo escriben personas de confianza. Si se pierde una cuenta de administrador, php artisan bookstack:create-admin crea otra, y php artisan bookstack:reset-mfa retira la doble autenticación de un usuario.

Copias de seguridad y actualizaciones

Una copia de seguridad completa reúne la base y las cuatro ubicaciones de archivos propias de su instancia. Las exportaciones de contenido sirven para otra cosa: la documentación precisa que no sustituyen a una copia de seguridad.

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

La primera línea se dirige a una instalación por script, donde el root de MySQL se conecta mediante sudo; en otros casos, escriba mysqldump -u bookstack -p bookstack. Guarde esos dos archivos aparte, preferiblemente en otra máquina. El archivo comprimido contiene .env, es decir, APP_KEY y sus contraseñas: trátelo como un secreto.

Restaurar

En una máquina nueva, instale BookStack sin ejecutar php artisan migrate, un paso que hay que comentar en el script si lo usa, y restaure después la base y los archivos, conservando la APP_KEY original:

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

Si la versión instalada es más reciente que la copia, ejecute después php artisan migrate. Restablezca los permisos de escritura del servidor web en las carpetas restauradas. Si la dirección ha cambiado, corrija APP_URL y ejecute bookstack:update-url.

Actualizar

Haga copia de la base y de los archivos antes de cada actualización y, después, desde la carpeta de BookStack:

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

El script para Ubuntu 26.04 instala BookStack sin Composer. La página de las actualizaciones propone entonces, en beta, ./bookstack-system-cli download-vendor en lugar de composer install --no-dev. Esa misma herramienta sabe copiar y restaurar, pero el proyecto aún no la considera lista para producción: pruébela antes de fiarse de ella.

La documentación mantiene una lista de indicaciones propias de cada versión, que hay que leer para la versión que se vaya a instalar. Algunos ejemplos:

• Versión 26.09: APP_KEY pasa a ser obligatoria.
• Versión 26.05: la carpeta storage/fonts debe seguir siendo escribible para el servidor web, sin lo cual las exportaciones a PDF pueden fallar.
• Versión 26.03: pruebe el envío de correos tras la actualización.
• Versión 25.11: grandes cambios en la base, cuya migración puede tardar varios minutos en una instancia grande.

Los fallos se corrigen en versiones de mantenimiento, como la 26.09.3 del 11 de noviembre de 2026: las imágenes y los dibujos de una página en borrador o en la papelera seguían siendo accesibles y modificables, y el borrador personal de un editor podía quedar visible para otras personas.

Quién hace qué en un VPS administrado

El autoalojamiento exige mantener el servidor además de la aplicación. En un VPS administrado, nuestros equipos se encargan del servidor y siguen su instancia de forma proactiva; BookStack sigue siendo su software, con sus ajustes y sus datos.

Si prefiere que nuestros equipos intervengan en la propia aplicación, ese servicio se factura por horas o a precio cerrado, con un presupuesto comunicado antes de la intervención.