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