Skip to main content

Actualización manual de BookStack

Instalación por release / tarball (procedimiento— reforzado)Procedimiento normativo

⚠️ REGLAS DE INTERPRETACIÓN (LECTURA OBLIGATORIA)

Este documento DocumentoNO operativo,es nouna guía genérica.
Describe este tipo de sistema y este método de instalacióngenérica.
NO describe “cómo se suele actualizar BookStack”.

Describe ÚNICAMENTE este escenario concreto:

    Instalación por release / tarball Sin uso de Git Con swap controlado de directorios Con backups ya existentes

    Si algoalguna instrucción no coincideencaja exactamente con el estadosistema descrito,real:

    → NO se adapta
    → NO se improvisa
    → NO se proponen alternativas
    → SE DETIENE EL PROCESO

    No existen “variantes equivalentes” de este procedimiento.
    Si algo no está escrito aquí, NO forma parte del proceso.

    0. EstadoESTADO inicialINICIAL verificado— (OBLIGATORIO)CONDICIÓN DE EJECUCIÓN

    AntesSI ALGUNO DE LOS SIGUIENTES PUNTOS NO SE CUMPLE,
    ESTE PROCEDIMIENTO NO ES APLICABLE.

    Debe verificarse antes de empezar,hacer todo esto debe ser ciertonada:

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

    Ejemplo:

    v25.12.2

    Si algunola de estos puntos no se cumple,versión no continuar.puede verificarse, NO continuar.

    1. ProhibicionesPROHIBICIONES absolutasABSOLUTAS

    Durante todo el procedimientoproceso:, está prohibido:

    • ❌ NO usarUsar git clone, git pull, git checkout
    • ❌ NOActualizar actualizar “in place”directamente sobre /var/www/bookstack
    • ❌ NO copiarCopiar vendor/ desde la instalación viejaanterior
    • ❌ NO ejecutarEjecutar comandos fuera del directorio indicado
    • ❌ NO improvisarInventar rutas “equivalentes” o “más limpias”
    • ❌ NOEjecutar continuarpasos sifuera de orden
    ❌ Continuar tras un pasoerror fallasin o no queda claroentenderlo

    Este procedimiento es lineallineal, cerrado y controladodeliberado.

    2. BackupBACKUP (fueraFUERA deDE alcance de este documento)ALCANCE)

    Antes de seguir:continuar:

    • Backup completo del sistema realizado
    • VerificadoBackup queverificado puedecomo restaurarserestaurable

    Si no haySin backup, noNO se actualiza.

    3. PrepararPREPARACIÓN directorio— deENTORNO trabajoFUERA (fueraDE de producción)PRODUCCIÓN

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

    CheckpointCHECKPOINT

    • pwd devuelve /root/tmp-bookstack-update
    • NoProducción seNO ha tocadosido /var/www/bookstacktocada

    4. DescargarDESCARGA nuevaDE releaseLA NUEVA RELEASE

    Ejemplo para (v25.12.3: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

    CheckpointCHECKPOINT

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

    Si no, DETENER.

    5. CopiarCOPIA configuraciónDE yCONFIGURACIÓN datosY necesariosDATOS

    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

    CheckpointCHECKPOINT

    • bookstack_NEW/.env existe en bookstack_NEW
    • storage/ existe dentroy decontiene bookstack_NEWdatos

    6. InstalarINSTALACIÓN dependenciasDE DEPENDENCIAS PHP

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

    CheckpointCHECKPOINT

    • ElComando comandofinaliza terminasin loerrores más limpio posiblefatales
    • Existe el directorio vendor/
    • vendor/ NO ha sido copiado manualmente

    Si falla, noNO continuar.

    7. EjecutarMIGRACIONES migracionesDE BASE DE DATOS

    php artisan migrate --force

    Resultado habitual:

    Nothing to migrate.

    CheckpointCHECKPOINT

    • No hay errores
    • Si hayaparecen migraciones, se leenleerlas antes de continuar

    8. SwapRECORDATORIO controladoCRÍTICO ANTES DEL SWAP

    Hasta este punto:

      Producción NO ha sido modificada Todo el trabajo ocurrió fuera de /var/www/bookstack Cualquier error aquí es reversible

      A partir del siguiente paso, se toca producción.

      9. SWAP CONTROLADO (ÚNICOPASO paso crítico)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

      CheckpointCHECKPOINT

      • /var/www/bookstack existe
      • Propietario correcto: www-data
      • La carpetaCarpeta OLD siguepermanece intacta

      9.10. LimpiezaLIMPIEZA deDE cacheCACHE yY recarga de PHPRECARGA

      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.11. VerificaciónVERIFICACIÓN finalFINAL

      • 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.12. RollbackROLLBACK inmediatoINMEDIATO (siSI algoALGO falla)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.

      NotaNOTA paraFINAL IAPARA OPERADOR / operador futuroIA

      Este documento NO es genériconormativo.

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

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

      Fin.Fin del procedimiento.

      Back to top