Actualizar a una versión nueva

Actualizar es cambiar el código y aplicar las migraciones de la base de datos. El orden importa y empieza siempre por una copia: una migración no siempre se puede deshacer.

Si lo tienes montado sin Docker, los pasos de abajo se pueden hacer de una vez con deploy/deploy.sh, el script del repositorio. Se lanza en el propio servidor, desde el clon, y solo trae el código del repositorio público. Hace, por orden: se niega a seguir si el clon tiene cambios locales; trae las etiquetas; lanza la copia (kosmotheka-backup.service); cambia el código a la versión que le pidas; instala las dependencias; aplica las migraciones; renueva la caché; reinicia los servicios; y, si se lo pides, comprueba que el servidor responde. Al acabar dice cómo volver atrás.

deploy/deploy.sh            # la última etiqueta (vX.Y.Z)
deploy/deploy.sh v0.3.0     # una etiqueta concreta
deploy/deploy.sh main       # la punta de main (para probar)

Se ajusta con variables de entorno, o con un archivo deploy/deploy.env junto al script (no se sube a git): KOSMOTHEKA_DIR (el clon), APP_USER (si lo lanzas como root: el usuario dueño del clon, que es quien ejecuta PHP), PHP_BIN (por defecto php8.5), COMPOSER_BIN, BACKUP_UNIT (la copia previa; vacía, se salta), RESTART_UNITS (por defecto php8.5-fpm kosmotheka-worker), BUILD_DOCS=1 (construye también la documentación; necesita Node 22.12 o más), NODE_DIR (la carpeta con el node y el npm para construirla, si no son los del sistema; con nvm, la carpeta bin de la versión, por ejemplo /home/usuario/.nvm/versions/node/v22.23.2/bin) y HEALTH_URL (por ejemplo https://tu-dominio/v1/server). Lee las notas de la versión antes de lanzarlo, y las variables nuevas que pidan, antes que el script. Lo que sigue es lo que hace, paso a paso, por si lo prefieres a mano o algo falla.

Antes: lee las notas de la versión

Las notas de cada versión dicen si hay algo especial. Dos casos que importan:

• Primero la app nueva en las tiendas, después el servidor, cuando las notas de la versión lo digan (la 0.2.1 lo pedía). Si el servidor cambia cómo se entra o cómo se firma, las apps viejas dejan de poder conectarse hasta que se actualizan; si primero esperas a que la gente tenga la app nueva, nadie se queda fuera.
• Algunas versiones piden un paso extra tras migrar (por ejemplo, volver a sellar las claves de la nube, o reconstruir el catálogo de las bibliotecas). Lo dicen las notas.

Los pasos

Con el ejemplo del sitio de la guía, /srv/kosmotheka:

# 1. Copia (la del temporizador, o una a mano ahora)
sudo systemctl start kosmotheka-backup.service

# 2. Código nuevo
cd /srv/kosmotheka
git fetch --tags
git checkout vX.Y.Z

# 3. Dependencias
cd server
php8.5 /usr/bin/composer install --no-dev --optimize-autoloader

# 4. Migraciones
php8.5 bin/console doctrine:migrations:migrate --no-interaction

# 5. Vaciar la caché
php8.5 bin/console cache:clear

# 6. Reiniciar PHP-FPM y el servicio de tareas
sudo systemctl restart php8.5-fpm kosmotheka-worker

Después, comprueba que responde: curl -s https://tu-dominio/v1/server.

Si hay una variable nueva en las notas, añádela a .env.local antes del paso 4. .env.local no se toca al actualizar el código.

Si algo sale mal

• Falla una migración: no sigas. Léela y busca la causa; una migración se ejecuta dentro de una transacción y, si falla, no deja cambios a medias.
• El código nuevo no arranca: vuelve al código anterior (git checkout de la etiqueta anterior) si las migraciones no llegaron a aplicarse. Si ya se aplicaron, restaura la copia del paso 1 (ver restaurar) y el código anterior juntos.
• Una migración no se deshace: alguna lo dice (su down lanza un error a propósito). Por eso la copia es el paso 1.