Skip to main content

Actualización manual de BookStack

Instalación por release / tarball (procedimiento reforzado)

ProcedimientoDocumento seguro,operativo, probadono guía genérica.
Describe este tipo de sistema y repetible.este método de instalación.
VálidoSi paraalgo instalacionesno coincide con el estado descrito, NOSE gitDETIENE EL PROCESO, como la tuya..

0. CondicionesEstado previasinicial verificado (OBLIGATORIO)

Antes de empezar, todo esto debe ser cierto:

  • BookStackMétodo instaladode porinstalación: release / tarball (.tar.gz)NO git)
  • PHPRuta activa de BookStack: /var/www/bookstack
  • Usuario propietario: www-data:www-data
  • PHP-FPM funcionando (php-fpm)
  • Base de datos operativa
  • Usuariopublic/uploads web:puede www-dataser directorio o symlink (válido)
  • Backups bajo control (restic, snapshots, etc.)

1. ComprobarLa 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

3.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/

4.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

⚠️

    No
  • bookstack_NEW/.env copiarexiste
  • storage/ existe dentro de vendor/bookstack_NEW
    • desde la instalación vieja.

5.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

Esperar sin interrumpir.
Si falla, no seguircontinuar.

6.7. Ejecutar migraciones

php artisan migrate --force

Resultado habitual:

Nothing to migrate.

Checkpoint

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

7.8. Swap controlado de(ÚNICO versionespaso 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

8.9. LimpiarLimpieza de cache y recargarrecarga 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

9.10. Verificación final

  • AccederAcceso víaweb navegadorcorrecto
  • ComprobarLogin loginfuncional
  • Verificar subidaSubida de imágenes correcta
  • ConfirmarVersión versión:confirmada:
cat /var/www/bookstack/version

Debe mostrar la nueva versión.

10.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.

NotasNota importantespara IA / operador futuro

Este documento NO es genérico.

  • No usarasumir gitconfiguraciones pull en instalaciones por release.distintas
  • No mezclar“mejorar” métodosel de actualización.procedimiento
  • ActualizarNo soloañadir cuandopasos “equivalentes”
  • No cambiar el orden

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

  • Repetir siempre este mismo procedimiento.

    • Fin.

    Back to top