Skip to main content

Actualización manual de BookStack

Instalación por release / tarball — Procedimiento normativo

⚠️ REGLAS DE INTERPRETACIÓN (LECTURA OBLIGATORIA)

Este documento NO es una guía gené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 alguna instrucción no encaja exactamente con el sistema 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. ESTADO INICIAL — CONDICIÓN DE EJECUCIÓN

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

Debe verificarse antes de hacer nada:

  • Método de instalación: release / tarball (NO git)
  • Ruta activa de BookStack: /var/www/bookstack
  • Usuario propietario: www-data:www-data
  • PHP-FPM operativo
  • Base de datos accesible
  • public/uploads existe (directorio o symlink válido)
  • Versión actual verificable con:
cd /var/www/bookstack
cat version

Ejemplo:

v25.12.2

Si la versión no puede verificarse, NO continuar.

1. PROHIBICIONES ABSOLUTAS

Durante todo el proceso, está prohibido:

  • ❌ Usar git clone, git pull, git checkout
  • ❌ Actualizar directamente sobre /var/www/bookstack
  • ❌ Copiar vendor/ desde la instalación anterior
  • ❌ Ejecutar comandos fuera del directorio indicado
  • ❌ Inventar rutas “equivalentes” o “más limpias”
  • ❌ Ejecutar pasos fuera de orden
  • ❌ Continuar tras un error sin entenderlo

Este procedimiento es lineal, cerrado y deliberado.

2. BACKUP (FUERA DE ALCANCE)

Antes de continuar:

  • Backup completo del sistema realizado
  • Backup verificado como restaurable

Sin backup, NO se actualiza.

3. PREPARACIÓN — ENTORNO FUERA DE PRODUCCIÓN

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

CHECKPOINT

  • pwd devuelve /root/tmp-bookstack-update
  • Producción NO ha sido tocada

4. DESCARGA DE LA NUEVA RELEASE

Ejemplo (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/

Si no, DETENER.

5. COPIA DE CONFIGURACIÓN Y DATOS

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

  • .env existe en bookstack_NEW
  • storage/ existe y contiene datos

6. INSTALACIÓN DE DEPENDENCIAS PHP

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

CHECKPOINT

  • Comando finaliza sin errores fatales
  • Existe el directorio vendor/
  • vendor/ NO ha sido copiado manualmente

Si falla, NO continuar.

7. MIGRACIONES DE BASE DE DATOS

php artisan migrate --force

Resultado habitual:

Nothing to migrate.

CHECKPOINT

  • No hay errores
  • Si aparecen migraciones, leerlas antes de continuar

8. RECORDATORIO CRÍ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 (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
  • Carpeta OLD permanece intacta

10. LIMPIEZA DE CACHE Y RECARGA

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

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

12. 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 FINAL PARA OPERADOR / IA

Este documento es normativo.

  • No asumir configuraciones distintas
  • No “optimizar” el proceso
  • No añadir pasos
  • No cambiar el orden

Si el sistema real no coincide con este documento,
se documenta primero y se adapta después.

Fin del procedimiento.