Instalación de BookStack en

Copias de seguridad y mantenimiento

Las copias de seguridad regulares son la piedra angular de cualquier sistema en producción. BookStack almacena datos en la base de datos y archivos (imágenes, adjuntos) en el disco. El mantenimiento incluye actualizaciones de software y monitorización.

1. Qué respaldar

• Base de datos de BookStack: Contiene todas las páginas, libros, capítulos, usuarios y configuraciones. Esto es lo más importante.
• Archivos de BookStack: Incluyen imágenes subidas, adjuntos, así como el archivo .env (con datos confidenciales como la clave de la aplicación y las credenciales de la base de datos).

2. Script simple de copia de seguridad automática

Crearemos un script simple para la copia de seguridad. Se recomienda no almacenar las copias de seguridad en el mismo servidor.

sudo nano /usr/local/bin/bookstack_backup.sh

Pegue el siguiente contenido, reemplazando ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД y bookstack_db con sus propios valores:

#!/bin/bash

# Configuración
DB_NAME="bookstack_db"
DB_USER="bookstack_user" # Es mejor crear un usuario MySQL separado solo para copias de seguridad con permisos SELECT, LOCK TABLES
DB_PASS="SU_CONTRASEÑA_SEGURA_PARA_LA_BD"
BOOKSTACK_PATH="/var/www/bookstack"
BACKUP_DIR="/var/backups/bookstack"
DATE=$(date +%Y%m%d%H%M%S)
FILENAME_DB="${DB_NAME}_${DATE}.sql"
FILENAME_FILES="bookstack_files_${DATE}.tar.gz"

# Creación del directorio para copias de seguridad, si no existe
mkdir -p "${BACKUP_DIR}"

echo "Iniciando la copia de seguridad de BookStack..."

# 1. Copia de seguridad de la base de datos
echo "Copia de seguridad de la base de datos..."
mysqldump --user="${DB_USER}" --password="${DB_PASS}" "${DB_NAME}" > "${BACKUP_DIR}/${FILENAME_DB}"
if [ $? -eq 0 ]; then
    echo "Copia de seguridad de la base de datos creada con éxito: ${FILENAME_DB}"
else
    echo "Error al crear la copia de seguridad de la base de datos."
    exit 1
fi

# 2. Copia de seguridad de los archivos de BookStack (excluyendo caché y logs)
echo "Copia de seguridad de los archivos de BookStack..."
tar -czf "${BACKUP_DIR}/${FILENAME_FILES}" -C "${BOOKSTACK_PATH}" \
    --exclude='storage/uploads/images/*' \
    --exclude='storage/uploads/files/*' \
    --exclude='storage/logs/*' \
    --exclude='bootstrap/cache/*' \
    --exclude='vendor/*' \
    .
# Adicionalmente, guardamos solo .env y uploads por separado para facilitar su restauración
cp "${BOOKSTACK_PATH}/.env" "${BACKUP_DIR}/bookstack_env_${DATE}.env"
tar -czf "${BACKUP_DIR}/bookstack_uploads_images_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" images
tar -czf "${BACKUP_DIR}/bookstack_uploads_files_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" files

if [ $? -eq 0 ]; then
    echo "Copia de seguridad de los archivos de BookStack creada con éxito: ${FILENAME_FILES}"
else
    echo "Error al crear la copia de seguridad de los archivos de BookStack."
    exit 1
fi

# 3. Eliminación de copias de seguridad antiguas (por ejemplo, de más de 7 días)
echo "Eliminando copias de seguridad antiguas..."
find "${BACKUP_DIR}" -type f -name "*.sql" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name "*.tar.gz" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name "*.env" -mtime +7 -delete

echo "Copia de seguridad completada."

Guarde el archivo y hágalo ejecutable:

sudo chmod +x /usr/local/bin/bookstack_backup.sh

3. Automatización de copias de seguridad con Cron

Añadiremos el script al planificador Cron para su ejecución diaria.

sudo crontab -e

Seleccione un editor de texto (si se le solicita) y añada la siguiente línea al final del archivo para ejecutar la copia de seguridad cada día a las 3:00 de la madrugada:

0 3 * * * /usr/local/bin/bookstack_backup.sh >> /var/log/bookstack_backup.log 2>&1

Guarde y salga. Ahora las copias de seguridad se crearán automáticamente.

4. Dónde almacenar las copias de seguridad

¡Nunca almacene todas las copias de seguridad solo en el mismo servidor que el servicio principal! Si el servidor falla, perderá todo.

• Almacenamiento externo compatible con S3: Amazon S3, DigitalOcean Spaces, Backblaze B2. Esta es una opción fiable y relativamente económica. Puede utilizar utilidades como s3cmd o rclone para la sincronización automática.
• VPS separado: Alquile un VPS pequeño y económico exclusivamente para almacenar copias de seguridad y sincronícelas allí mediante SFTP/RSYNC.
• Unidad de red local (NAS): Si tiene su propia infraestructura.

Por ejemplo, para enviar copias de seguridad a S3, puede añadir al script bookstack_backup.sh, después de crear los archivos, el comando s3cmd put "${BACKUP_DIR}/${FILENAME_DB}" s3://your-s3-bucket/bookstack/ (requerirá la instalación y configuración de s3cmd).

5. Actualizaciones: rolling vs maintenance window

Las actualizaciones regulares son cruciales para la seguridad y para obtener nuevas funciones.

• Actualizaciones del sistema (SO, PHP, MySQL):
  • Rolling (continuas): Para parches de seguridad no críticos, se pueden configurar actualizaciones automáticas (por ejemplo, con unattended-upgrades).
  • Maintenance Window (ventana de mantenimiento): Para actualizaciones mayores de PHP, MySQL o el kernel de Linux, se recomienda planificar una ventana de mantenimiento, ya que pueden requerir un reinicio del servidor o provocar una interrupción temporal del servicio. Pruebe las actualizaciones en un servidor de staging, si es posible.

  
  sudo apt update && sudo apt upgrade -y # Actualización del sistema
  

• Actualizaciones de BookStack:

  BookStack se actualiza a través de Git y Composer. Se recomienda realizarlas durante una ventana de mantenimiento.

  
  cd /var/www/bookstack
  git pull # Descarga los últimos cambios del repositorio
  composer install --no-dev # Actualiza las dependencias
  php artisan migrate --force # Ejecuta las migraciones de la base de datos (si las hay)
  php artisan cache:clear # Limpia la caché de BookStack
  php artisan view:clear # Limpia la caché de las vistas
  sudo chown -R www-data:www-data /var/www/bookstack # Asegúrese de que los permisos son correctos después del pull
  sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache
  sudo systemctl reload php8.3-fpm # Reinicia PHP-FPM
  sudo systemctl reload caddy # Reinicia Caddy
  

  Siempre consulte la documentación oficial de BookStack antes de actualizar, ya que el proceso puede cambiar.

Solución de problemas + FAQ

Mi BookStack no funciona, veo un error 500 o una página en blanco. ¿Qué debo hacer?

El error 500 (Internal Server Error) suele indicar un problema en el funcionamiento de PHP o de la aplicación. En primer lugar, revise los logs:

• Logs de Caddy: sudo tail -f /var/log/caddy/access.log y sudo journalctl -u caddy -f. Busque errores relacionados con el proxying de PHP.
• Logs de PHP-FPM: sudo tail -f /var/log/php8.3-fpm.log (o la versión de PHP correspondiente).
• Logs de BookStack: sudo tail -f /var/www/bookstack/storage/logs/laravel.log. Este es el log más importante para depurar problemas del propio BookStack.

Causas frecuentes: permisos de acceso incorrectos a archivos/directorios (especialmente storage y bootstrap/cache), errores en el archivo .env (credenciales de base de datos incorrectas, APP_URL erróneo), extensiones PHP faltantes, problemas de conexión a la base de datos.

¿Qué configuración mínima de VPS es adecuada para BookStack?

Para un uso personal pequeño o un equipo de 2-3 personas con un volumen de datos no muy grande, un VPS con 1-2 vCPU, 2 GB de RAM y 40 GB de disco SSD será suficiente. Esto es adecuado para el funcionamiento estable de Ubuntu 24.04 LTS, PHP 8.3/8.4, MySQL 8.0 y Caddy con BookStack. Es importante que el disco sea SSD para un buen rendimiento de la base de datos.

¿Qué elegir: VPS o dedicado para esta tarea?

Para la mayoría de los escenarios de uso de BookStack (wiki personal, base de conocimientos para un equipo pequeño o mediano de hasta 30-50 personas), un VPS es la opción óptima. Ofrece suficiente rendimiento, flexibilidad y un coste significativamente menor. Un servidor dedicado debe considerarse si tiene un equipo muy grande (cientos de usuarios), un volumen de datos enorme, requisitos críticos de rendimiento sin compromisos, o si planea alojar muchas otras aplicaciones que consumen muchos recursos en el mismo servidor.

He cambiado el nombre de dominio. ¿Qué necesito actualizar?

Si ha cambiado el nombre de dominio, debe actualizar al menos dos lugares:

1. Archivo .env de BookStack: Cambie el valor de APP_URL al nuevo nombre de dominio (por ejemplo, APP_URL=https://new-domain.com).
2. Caddyfile: Edite /etc/caddy/Caddyfile y reemplace el nombre de dominio antiguo por el nuevo en la primera línea (por ejemplo, new-domain.com { ... }).

¿Cómo actualizar BookStack a una nueva versión?

El proceso de actualización de BookStack generalmente incluye: navegar al directorio de BookStack (cd /var/www/bookstack), obtener los últimos cambios de Git (git pull), actualizar las dependencias de PHP a través de Composer (composer install --no-dev), ejecutar las migraciones de la base de datos (php artisan migrate --force) y limpiar la caché de BookStack (php artisan cache:clear && php artisan view:clear). Siempre se recomienda leer las instrucciones oficiales de actualización para la versión específica de BookStack, ya que puede haber pasos específicos.

BookStack muestra un error "Access Denied" al intentar conectarse a MySQL.

Este error significa que BookStack no puede conectarse a la base de datos MySQL con las credenciales proporcionadas. Verifique lo siguiente:

• Archivo .env: Asegúrese de que DB_USERNAME, DB_PASSWORD y DB_DATABASE en el archivo /var/www/bookstack/.env coinciden exactamente con los que creó en MySQL.
• Usuario de MySQL: Asegúrese de que el usuario bookstack_user existe en MySQL y tiene los privilegios correctos sobre la base de datos bookstack_db. Puede verificar esto iniciando sesión en MySQL como root y ejecutando SELECT user, host FROM mysql.user; y SHOW GRANTS FOR 'bookstack_user'@'localhost';.
• Servicio de MySQL: Verifique que el servicio de MySQL esté en ejecución: sudo systemctl status mysql.

Conclusiones y próximos pasos

¡Felicidades! Ha instalado y configurado BookStack con éxito en su VPS, creando una plataforma fiable y controlada por usted para la gestión del conocimiento. Ahora tiene una potente herramienta para organizar información, ya sean notas personales, documentación de proyectos o una extensa base de conocimientos para su equipo. Ha obtenido control total sobre los datos y la infraestructura, garantizando la confidencialidad y la seguridad.

¿Qué sigue?

• Configuración de usuarios y roles: En BookStack, puede crear usuarios, grupos y asignarles diferentes derechos de acceso a libros, capítulos y páginas. Comience creando cuentas para su equipo y configurando los permisos correspondientes.
• Personalización de la apariencia: BookStack le permite cambiar el logotipo, el esquema de colores y añadir CSS personalizado para adaptar su wiki a su estilo.
• Integración con servicios externos: Considere configurar el inicio de sesión único (SSO) a través de LDAP, SAML2 o proveedores sociales, si es relevante para su equipo.
• Monitorización del servidor: Instale sistemas de monitorización (por ejemplo, Prometheus + Grafana o Zabbix) para rastrear la carga de CPU, RAM, disco y el estado de los servicios, con el fin de reaccionar rápidamente a posibles problemas.