Operación en el host

Comandos para inspeccionar y operar los servicios directamente en el host de un entorno. Todos se ejecutan desde el directorio del stack:

cd ${DEPLOY_BASE_PATH}/idp            # auth-backend y frontends del IDP
cd ${DEPLOY_BASE_PATH}/seleccionador  # backend y frontends del SPS
cd ${DEPLOY_BASE_PATH}/docs           # manuales

INFO

La forma normal de desplegar es mediante los pipelines. Las operaciones manuales de esta página son para diagnóstico y contingencias; el siguiente despliegue vuelve a aplicar la configuración de infra-deploy.

Estado de los servicios

docker compose ps

Columna STATUS:

Estado	Significado
Up (healthy)	Contenedor en ejecución y /health/ responde
Up (health: starting)	Dentro del start_period (20 s backends, 5 s frontends)
Up (unhealthy)	En ejecución, pero el health check falló 3 veces seguidas
Restarting	El proceso termina y Docker lo reinicia (restart: unless-stopped)

Detalle del último health check:

docker inspect --format '{{json .State.Health}}' auth-backend

Uso de recursos:

docker stats --no-stream

Logs

# Últimas 200 líneas
docker compose logs --tail 200 backend-seleccion-postulantes

# En vivo
docker compose logs -f backend-seleccion-postulantes

# Desde hace 30 minutos
docker compose logs --since 30m auth-backend

En los backends, la salida incluye los logs de acceso y error de gunicorn y la salida del entrypoint.sh (migraciones, collectstatic y comandos de arranque). Los logs rotan a 10 MB con 5 archivos por contenedor.

Reiniciar o recrear un servicio

# Reiniciar el proceso (misma imagen y configuración)
docker compose restart auth-backend

# Recrear el contenedor (relee back.env y .env)
docker compose up -d --force-recreate --no-deps auth-backend

TIP

restart no vuelve a leer env_file. Si cambió back.env, use up -d --force-recreate.

Actualizar a la última imagen

Equivale a lo que hace el pipeline para un servicio:

docker compose pull backend-seleccion-postulantes
docker compose up -d --no-deps backend-seleccion-postulantes

Requiere sesión iniciada en el registry (docker login git.eje.gob.bo:5050) con el deploy token del grupo.

Rollback a una versión anterior

Cada build publica un tag inmutable <rama>-<sha corto>. Para volver a una versión anterior de un servicio:

1. Identificar el tag en GitLab: Deploy → Container Registry del repositorio, o el SHA del commit en el historial de la rama.

2. Desplegar ese tag solo para el servicio afectado, sobrescribiendo IMAGE_TAG en la línea de comandos (tiene prioridad sobre .env):

   IMAGE_TAG=main-a1b2c3d4 docker compose pull auth-backend
   IMAGE_TAG=main-a1b2c3d4 docker compose up -d --no-deps auth-backend

3. Verificar con docker compose ps y los logs.

Para revertir el rollback, vuelva a desplegar con latest:

docker compose pull auth-backend
docker compose up -d --no-deps auth-backend

WARNING

• El siguiente despliegue del servicio por pipeline vuelve a <rama>-latest. Para que el rollback sea definitivo, revierta el commit en la rama y deje que el pipeline publique una nueva imagen.
• En los backends, entrypoint.sh aplica migraciones al arrancar, pero volver a una imagen anterior no revierte migraciones. Si la versión nueva incluía migraciones incompatibles, evalúe revertirlas con python manage.py migrate <app> <migracion> antes del rollback.

Ejecutar comandos dentro de un contenedor

# Shell interactiva (los backends corren como appuser)
docker compose exec backend-seleccion-postulantes bash

# Comando puntual
docker compose exec auth-backend python manage.py showmigrations

Los frontends usan nginx:alpine, que solo incluye sh:

docker compose exec frontend-portal-admin-seleccion-postulantes sh

Los comandos de gestión disponibles se describen en Scripts útiles de los backends.

Archivos de los backends

Los archivos de los backends persisten en el host, fuera de los contenedores:

${DEPLOY_BASE_PATH}/idp/storage/{public,private}
${DEPLOY_BASE_PATH}/seleccionador/storage/{public,private}

Recrear o eliminar un contenedor no afecta estos directorios. Inclúyalos en el respaldo del entorno junto con las bases de datos.

Detener servicios

# Detener un servicio (no se reinicia automáticamente)
docker compose stop frontend-estacion-examen

# Volver a iniciarlo
docker compose start frontend-estacion-examen

DANGER

Evite docker compose down -v en los stacks: aunque los volúmenes actuales son directorios del host (bind mounts), el comando elimina contenedores y redes del stack y deja todos los servicios fuera de línea hasta un nuevo despliegue.

Limpieza de imágenes

Cada docker compose pull mueve <rama>-latest a la imagen nueva y la anterior queda sin tag (<none>); además pueden quedar tags <rama>-<sha> (builds en el mismo daemon o rollbacks manuales ya revertidos). El job deploy-orquestador los limpia al final de cada despliegue con scripts/cleanup-project-images.sh de infra-deploy. El job build de cada repositorio hace lo mismo en el daemon del runner (ver Pipelines CI/CD).

Qué se elimina

Solo imágenes que cumplen todas estas condiciones:

1. Pertenecen a un repositorio de los docker-compose.yml de infra-deploy (coincidencia exacta, p. ej. git.eje.gob.bo:5050/proceso-seleccion/auth-backend) dentro de HOST_CLEANUP_NAMESPACE. Cualquier otro repositorio aborta el script sin cambios.
2. No tienen tag, o solo tienen tags inmutables develop-<sha> / main-<sha> del mismo repositorio (siempre pueden volver a descargarse del registry). Nunca se tocan imágenes con <rama>-latest ni con otros tags.
3. No las usa ningún contenedor del host, de ningún proyecto y en ningún estado.
4. Sus digests no pertenecen a otro repositorio.
5. No están entre las HOST_IMAGE_KEEP_PREVIOUS (2) más recientes de su repositorio, que se conservan para rollback local.

Se eliminan con docker image rm sin --force: si Docker detecta cualquier referencia, la imagen se conserva. No se tocan contenedores, volúmenes, redes, caché de compilación ni imágenes de otros proyectos. El log del job lista cada imagen conservada (con el motivo) y cada imagen eliminada.

Configuración

Variable (job deploy-orquestador)	Por defecto	Descripción
HOST_CLEANUP_MODE	apply	apply elimina; dry-run solo lista
HOST_IMAGE_KEEP_PREVIOUS	2	Imágenes anteriores conservadas por servicio
HOST_CLEANUP_NAMESPACE	git.eje.gob.bo:5050/proceso-seleccion	Único namespace que se puede limpiar

La limpieza corre en el host del entorno que se despliega (develop → test, main → producción). Valide primero en test revisando el log del job antes de llevar el cambio a main.

Para revisar a mano qué se eliminaría en un host (desde una copia de infra-deploy):

bash scripts/cleanup-project-images.sh \
  --namespace git.eje.gob.bo:5050/proceso-seleccion --mode dry-run \
  git.eje.gob.bo:5050/proceso-seleccion/auth-backend

DANGER

No use docker image prune, docker system prune ni docker volume prune en este host: es compartido y esos comandos afectan imágenes, caché y volúmenes de otros proyectos.

Rollback y retención

• Local: las 2 imágenes anteriores de cada servicio siguen en el host. Se identifican con docker image ls git.eje.gob.bo:5050/proceso-seleccion/<servicio>.
• Registry: el rollback documentado arriba usa los tags inmutables <rama>-<sha> del Container Registry, que dependen de su política de limpieza.

Política de limpieza del Container Registry

Se recomienda configurarla en cada repositorio de imagen (Settings → Packages and registries → Clean up image tags):

Parámetro	Valor
Ejecutar limpieza	Cada día
Conservar los más recientes	10 tags por imagen
Conservar tags que coincidan	.*-latest
Eliminar tags más antiguos que	30 días
Eliminar tags que coincidan	(develop|main)-[0-9a-f]+

Un tag solo se elimina si no está entre los 10 más recientes y tiene más de 30 días, así que siempre quedan disponibles los últimos 10 builds para rollback. Equivalente por API (token con rol Maintainer):

curl -fsS -X PUT -H "PRIVATE-TOKEN: $TOKEN" \
  --data-urlencode 'container_expiration_policy_attributes[enabled]=true' \
  --data-urlencode 'container_expiration_policy_attributes[cadence]=1d' \
  --data-urlencode 'container_expiration_policy_attributes[keep_n]=10' \
  --data-urlencode 'container_expiration_policy_attributes[older_than]=30d' \
  --data-urlencode 'container_expiration_policy_attributes[name_regex]=(develop|main)-[0-9a-f]+' \
  --data-urlencode 'container_expiration_policy_attributes[name_regex_keep]=.*-latest' \
  "https://git.eje.gob.bo/api/v4/projects/proceso-seleccion%2F<repositorio>"

WARNING

• Si producción necesita rollback a versiones de más de 30 días con más de 10 builds posteriores, agregue main-.* a "Conservar tags que coincidan".
• La política elimina tags; el espacio en disco del registry se libera cuando el administrador de GitLab ejecuta el garbage collector del registry.