Actualizar una web sin cortes: despliegues con releases y un enlace simbólico
Si actualizas tu web copiando archivos encima, durante un rato sirve una mezcla de versiones. Así desplegamos: cada versión en su carpeta y un cambio instantáneo.
En este artículo
La forma más sencilla de actualizar una web es entrar al servidor y hacer git pull o copiar los archivos encima. Funciona, pero durante ese rato la web sirve una mezcla: código nuevo que llama a archivos viejos. Si algo sale mal a medias, no es fácil volver atrás.
Nuestras webs usan otra estructura, muy sencilla, que resuelve las dos cosas: cada versión vive en su propia carpeta y pasar de una a otra es un solo cambio.
La estructura
/var/www/app/
├── current -> releases/20261103173038 la versión que se está sirviendo
├── releases/
│ ├── 20261103173037/
│ └── 20261103173038/
└── shared/ lo que sobrevive entre versiones
├── .env
├── data/
└── uploads/releases/: una carpeta completa por versión. Una vez publicada, no se toca.shared/: la configuración, la base de datos y los archivos subidos. Cada versión los enlaza.current: un enlace simbólico a la versión activa. Es la carpeta que sirve el servidor web.
El script
#!/bin/sh
set -eu
APP=$1 # carpeta de la app; shared/ ya debe existir
FUENTE=$2 # carpeta con el código nuevo
NUEVA="$APP/releases/$(date +%Y%m%d%H%M%S)"
mkdir -p "$NUEVA" "$APP/shared/data"
cp -R "$FUENTE/." "$NUEVA/"
ln -s "$APP/shared/data" "$NUEVA/data" # lo que sobrevive entre versiones
# Aquí, dentro de la versión nueva: instalar dependencias y migrar la base
ln -s "$NUEVA" "$APP/current.tmp" # el cambio: crear el enlace y renombrarlo encima
mv -T "$APP/current.tmp" "$APP/current"
ls -1dt "$APP"/releases/* | tail -n +6 | xargs rm -rf # se quedan las 5 últimasTodo se prepara en una carpeta que nadie está sirviendo, así que si falla la instalación de dependencias, set -e detiene el script y la web sigue tal cual. La versión nueva solo entra en la penúltima línea.
Por qué renombrar el enlace y no borrarlo
Lo importante está en esas dos líneas: crear un enlace temporal y renombrarlo encima de current. En Linux, renombrar es una operación atómica: quien mire ve el enlace viejo o el nuevo, nunca un hueco. Borrar y volver a crear sí deja uno.
Lo medimos con tres procesos leyendo sin parar a través del enlace mientras otro lo cambiaba miles de veces durante tres segundos:
Forma de cambiarloLecturasFallidasBorrar y crear817 628556 145Crear y renombrar888 0780
Es una prueba exagerada a propósito: nadie despliega miles de veces en tres segundos. Pero enseña la diferencia: uno tiene un instante sin enlace y el otro no.
La opción
-Tdemves de GNU, la que trae Linux. Sin ella,mvmetería el enlace temporal dentro de la carpeta a la que apuntacurrent. En macOS, la opción equivalente es-h.
Volver atrás
Si la versión nueva da problemas, basta con apuntar el enlace a la anterior:
ln -s /var/www/app/releases/20261103173037 /var/www/app/current.tmp
mv -T /var/www/app/current.tmp /var/www/app/currentTarda un instante, porque la versión anterior sigue entera en su carpeta.
Lo que hay que ajustar en Nginx y PHP
Con PHP hay una trampa: PHP guarda en caché las rutas reales y el código ya compilado. Si no lo tienes en cuenta, puede seguir sirviendo la versión anterior después del cambio. Dos ajustes lo resuelven.
En Nginx, pásale a PHP la ruta real, ya resuelta, con $realpath_root:
root /var/www/app/current/public;
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
fastcgi_pass unix:/run/php/php8.5-fpm.sock;
}Y, al final del despliegue, recarga PHP-FPM para vaciar la caché de código:
sudo systemctl reload php8.5-fpmEl límite: la base de datos
El código vuelve atrás en un instante; la base de datos no. Por eso conviene que los cambios de la base sean compatibles con la versión anterior: añadir una columna no le molesta al código viejo, pero borrarla o renombrarla sí. Si hay que eliminar algo, hazlo en un despliegue posterior, cuando ya nadie lo use.
¿Quieres dejar de cruzar los dedos cada vez que actualizas tu web? Hablemos.