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

          ⚠️

          Nobookstack_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