Skip to main content

Actualización manual de BookStack

Instalación por release / tarball (procedimiento reforzado)

Documento operativo, no guía genérica.
Describe este tipo de sistema y este método de instalación.
Si algo no coincide con el estado descrito, SE DETIENE EL PROCESO.

0. Estado inicial verificado (OBLIGATORIO)

Antes de empezar, todo esto debe ser cierto:

  • Método de instalación: release / tarball (NO git)
  • Ruta activa de BookStack: /var/www/bookstack
  • Usuario propietario: www-data:www-data
  • PHP-FPM funcionando
  • Base de datos operativa
  • public/uploads puede ser directorio o symlink (válido)
  • La versión actual se obtiene con:
cd /var/www/bookstack
cat version

Ejemplo:

v25.12.2

Si alguno de estos puntos no se cumple, no continuar.

1. Prohibiciones absolutas

Durante todo el procedimiento:

  • ❌ NO usar git clone, git pull, git checkout
  • ❌ NO actualizar “in place” sobre /var/www/bookstack
  • ❌ NO copiar vendor/ desde la instalación vieja
  • ❌ NO ejecutar comandos fuera del directorio indicado
  • ❌ NO improvisar rutas “equivalentes”
  • ❌ NO continuar si un paso falla o no queda claro

Este procedimiento es lineal y controlado.

2. Backup (fuera de alcance de este documento)

Antes de seguir:

  • Backup completo realizado
  • Verificado que puede restaurarse

Si no hay backup, no se actualiza.

3. Preparar directorio de trabajo (fuera de producción)

mkdir -p /root/tmp-bookstack-update
cd /root/tmp-bookstack-update

Checkpoint

  • pwd devuelve /root/tmp-bookstack-update
  • No se ha tocado /var/www/bookstack

4. Descargar nueva release

Ejemplo para v25.12.3:

wget https://github.com/BookStackApp/BookStack/archive/refs/tags/v25.12.3.tar.gz
tar xzf v25.12.3.tar.gz
mv BookStack-25.12.3 bookstack_NEW

Checkpoint

  • Existe bookstack_NEW/
  • Contiene artisan, public/, storage/

5. Copiar configuración y datos necesarios

Desde la instalación activa:

cp /var/www/bookstack/.env bookstack_NEW/
cp -a /var/www/bookstack/storage bookstack_NEW/
cp -a /var/www/bookstack/public/uploads bookstack_NEW/public/
cp /var/www/bookstack/public/custom.css bookstack_NEW/public/ 2>/dev/null || true

Checkpoint

  • bookstack_NEW/.env existe
  • storage/ existe dentro de bookstack_NEW

6. Instalar dependencias PHP

cd bookstack_NEW
composer install --no-dev --optimize-autoloader

Checkpoint

  • El comando termina lo más limpio posible
  • Existe el directorio vendor/
  • vendor/ NO ha sido copiado manualmente

Si falla, no continuar.

7. Ejecutar migraciones

php artisan migrate --force

Resultado habitual:

Nothing to migrate.

Checkpoint

  • No hay errores
  • Si hay migraciones, se leen antes de continuar

8. Swap controlado (ÚNICO paso crítico)

mv /var/www/bookstack /var/www/bookstack_OLD_$(date +%Y%m%d)
mv /root/tmp-bookstack-update/bookstack_NEW /var/www/bookstack
chown -R www-data:www-data /var/www/bookstack

Checkpoint

  • /var/www/bookstack existe
  • Propietario correcto: www-data
  • La carpeta OLD sigue intacta

9. Limpieza de cache y recarga de PHP

cd /var/www/bookstack
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan cache:clear
sudo systemctl reload php8.4-fpm

10. Verificación final

  • Acceso web correcto
  • Login funcional
  • Subida de imágenes correcta
  • Versión confirmada:
cat /var/www/bookstack/version

Debe mostrar la nueva versión.

11. Rollback inmediato (si algo falla)

rm -rf /var/www/bookstack
mv /var/www/bookstack_OLD_YYYYMMDD /var/www/bookstack
sudo systemctl reload php8.4-fpm

No investigar con producción rota.
Primero volver atrás, luego analizar.

Nota para IA / operador futuro

Este documento NO es genérico.

  • No asumir configuraciones distintas
  • No “mejorar” el procedimiento
  • No añadir pasos “equivalentes”
  • No cambiar el orden

Si el sistema no coincide con lo descrito aquí,
se documenta primero y se adapta después.

Fin.

Back to top