Alojar BookStack en su propio VPS

Por qué autoalojar BookStack en un VPS

Beneficios concretos de un BookStack autoalojado

• Estructura clara en estantes/libros/capítulos/páginas: documentación navegable sin esfuerzo.
• Editor WYSIWYG y Markdown a elección, con diagramas Draw.io integrados.
• Permisos granulares por rol y por libro para compartimentar los contenidos sensibles.
• Búsqueda de texto completo y rápida sobre el conjunto de la base de conocimiento.
• Autenticación LDAP, SAML u OAuth para integrarse con su directorio corporativo.
• Huella ligera: un VPS con 2 GB de RAM basta para la documentación de un equipo.
• Sin suscripción por usuario — número ilimitado de colaboradores sin coste adicional.

Requisitos de hardware y software

BookStack frente a alternativas autoalojadas

Desplace la tabla

Desplegar BookStack con Docker Compose y SSL

1. 01

   Preparar el VPS e instalar Docker

   Conéctese por SSH e instale Docker y el plugin Compose:

   curl -fsSL https://get.docker.com | sh
   apt install docker-compose-plugin
   mkdir -p /opt/bookstack && cd /opt/bookstack

   Verifique: docker compose version debe mostrar v2.x o superior. La imagen comunitaria lscr.io/linuxserver/bookstack es la más extendida y mejor mantenida para un despliegue en contenedores.

2. 02

   Crear el archivo docker-compose.yml

   Cree /opt/bookstack/docker-compose.yml con dos servicios — MariaDB y BookStack — en una red dedicada:

   services:
     mariadb:
       image: mariadb:10.11
       environment:
         MYSQL_ROOT_PASSWORD: changeme_root
         MYSQL_DATABASE: bookstack
         MYSQL_USER: bookstack
         MYSQL_PASSWORD: changeme_bk
       volumes:
         - ./data/mariadb:/var/lib/mysql
       networks: [bookstack]
   
     bookstack:
       image: lscr.io/linuxserver/bookstack:latest
       environment:
         PUID: 1000
         PGID: 1000
         APP_URL: https://wiki.sudominio.com
         DB_HOST: mariadb
         DB_USER: bookstack
         DB_PASS: changeme_bk
         DB_DATABASE: bookstack
         MAIL_DRIVER: smtp
         MAIL_HOST: smtp.sudominio.com
         MAIL_PORT: 587
         MAIL_FROM: [email protected]
         MAIL_USERNAME: [email protected]
         MAIL_PASSWORD: su_contrasena_smtp
       ports:
         - "6875:80"
       volumes:
         - ./data/bookstack:/config
       depends_on: [mariadb]
       networks: [bookstack]
   
   networks:
     bookstack:

   APP_URL debe coincidir exactamente con la URL HTTPS final. Un valor incorrecto rompe los enlaces internos y las subidas.

3. 03

   Lanzar la pila y comprobar los registros

   docker compose up -d
   docker compose logs -f bookstack

   En el primer arranque, BookStack ejecuta automáticamente las migraciones de Laravel para crear el esquema de la base de datos. Espere la línea Server running on http://0.0.0.0:80 antes de continuar — tarda entre 30 y 60 segundos.

4. 04

   Configurar el reverse proxy y el SSL

   Con Caddy (gestión automática del certificado):

   wiki.sudominio.com {
       reverse_proxy localhost:6875
   }

   Recargue Caddy: systemctl reload caddy.

   Con Nginx + Certbot:

   server {
       listen 80;
       server_name wiki.sudominio.com;
       return 301 https://$host$request_uri;
   }
   server {
       listen 443 ssl;
       server_name wiki.sudominio.com;
       ssl_certificate /etc/letsencrypt/live/wiki.sudominio.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/wiki.sudominio.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:6875;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }

   Obtenga el certificado con certbot --nginx -d wiki.sudominio.com.

5. 05

   Primera conexión y segurización de la cuenta admin

   Abra https://wiki.sudominio.com. La cuenta por defecto es [email protected] con la contraseña password. Cámbielas inmediatamente en Configuración → Perfil.

   Verifique después que SMTP funciona: Configuración → Configuración de correo electrónico → Enviar un correo de prueba. Si el test falla, revise los registros: docker compose logs bookstack | grep -i mail.

Configuración avanzada: SSO, LDAP y SAML

Hacer copias de seguridad y restaurar BookStack

#!/bin/bash
BACKUP_DIR=/var/backups/bookstack
mkdir -p $BACKUP_DIR
DATE=$(date +%Y%m%d)
docker exec $(docker ps -qf name=mariadb) \
  mysqldump -u bookstack -pchangeme_bk bookstack \
  > $BACKUP_DIR/bookstack-db-$DATE.sql
tar -czf $BACKUP_DIR/bookstack-uploads-$DATE.tar.gz /opt/bookstack/data/bookstack/uploads
find $BACKUP_DIR -mtime +14 -delete

Resolución de problemas: errores comunes

Problemas frecuentes y soluciones

• Error SMTP «Connection refused» o timeout: compruebe que MAIL_PORT corresponde al puerto real (587 para STARTTLS, 465 para SSL). Algunos servidores SMTP bloquean el puerto 25 saliente. Pruebe la conectividad desde el contenedor: docker exec -it bookstack curl -v telnet://smtp.sudominio.com:587.
• Permisos en storage/: error 500 o página en blanco: la carpeta /opt/bookstack/data/bookstack debe pertenecer al UID 1000 (variable PUID). Corrija con chown -R 1000:1000 /opt/bookstack/data/bookstack y reinicie el contenedor.
• Lentitud o timeout de MariaDB al arrancar: BookStack espera a que MariaDB esté lista. Si el contenedor BookStack se reinicia en bucle los primeros segundos, es normal. Añada un healthcheck al servicio mariadb en el Compose o espere 30 segundos antes de inspeccionar los registros.
• Las imágenes no se muestran tras un cambio de dominio: APP_URL debe coincidir exactamente con la URL HTTPS pública. Si cambia de dominio, actualice APP_URL en el Compose, reinicie el contenedor y ejecute php artisan bookstack:update-url desde dentro del contenedor para actualizar las URLs almacenadas en la base de datos.
• Las migraciones se detienen en el primer arranque (OOM): si el VPS tiene menos de 2 GB de RAM, las migraciones de Laravel pueden ser eliminadas por el OOM killer. Añada un fichero de swap de 2 GB (fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile) o aumente la RAM del VPS antes de reintentar.

Actualizar BookStack

cd /opt/bookstack
docker compose pull
docker compose up -d
docker compose logs -f bookstack

Para profundizar

• Alojar Nextcloud en un VPS — almacenamiento en la nube y colaboración documental.
• Alojar Gitea en un VPS — forja Git autoalojada para sus equipos de desarrollo.
• Authentik en un VPS — SSO de código abierto para centralizar la autenticación de BookStack y sus otras aplicaciones.