Restore¶

La restauración recupera la plataforma a partir de un backup verificado. El procedimiento completo (PostgreSQL + realms + configuración) tarda aproximadamente 20-30 minutos en un VPS estándar.

Prerrequisitos¶

Backup disponible y checksums verificados
Entorno Docker funcionando (Docker Engine activo)
Variables de entorno del .env disponibles (de la versión encriptada del backup)
Servicios detenidos o VPS limpio en caso de disaster recovery

Procedimiento de restauración¶

Paso 1 — Verificar el backup¶

BACKUP_PATH="/var/backups/identity-platform/TIMESTAMP_DEL_BACKUP"

# Verificar checksums
cd "${BACKUP_PATH}"
sha256sum -c checksums.sha256

# Verificar que el dump SQL es legible
zcat keycloak-db.sql.gz | head -5

# Verificar que los JSON de realms son válidos
jq . realm-realm-internal.json > /dev/null && echo "realm-internal OK"
jq . realm-realm-partners.json > /dev/null && echo "realm-partners OK"

Paso 2 — Restaurar la configuración¶

# Desencriptar el .env
gpg --batch \
  --passphrase "${BACKUP_PASSPHRASE}" \
  --decrypt "${BACKUP_PATH}/env.gpg" > /opt/identity-platform/.env

# Restaurar archivos de configuración (si aplica)
tar -xzf "${BACKUP_PATH}/config.tar.gz" -C /

# Verificar .env
source /opt/identity-platform/.env
echo "KC_HOSTNAME=${KC_HOSTNAME}"

Paso 3 — Levantar solo PostgreSQL¶

cd /opt/identity-platform

# Levantar solo la base de datos primero
docker compose up -d postgres

# Esperar a que esté listo
until docker compose exec postgres pg_isready -U "${KC_DB_USER}"; do
  echo "Esperando PostgreSQL..."
  sleep 2
done
echo "PostgreSQL listo"

Paso 4 — Restaurar la base de datos¶

# Eliminar y recrear la base de datos
docker compose exec postgres \
  psql -U "${KC_DB_USER}" -c "DROP DATABASE IF EXISTS ${KC_DB_NAME};"
docker compose exec postgres \
  psql -U "${KC_DB_USER}" -c "CREATE DATABASE ${KC_DB_NAME};"

# Restaurar desde el dump
zcat "${BACKUP_PATH}/keycloak-db.sql.gz" | \
  docker compose exec -T postgres \
  psql -U "${KC_DB_USER}" -d "${KC_DB_NAME}"

echo "Base de datos restaurada"

Paso 5 — Levantar Keycloak¶

docker compose up -d keycloak

# Esperar a que esté listo (puede tardar 30-60 segundos)
until curl -sf http://localhost:8080/health/ready; do
  echo "Esperando Keycloak..."
  sleep 5
done
echo "Keycloak listo"

Paso 6 — Verificar los realms¶

# Obtener token admin
ADMIN_TOKEN=$(curl -s -X POST \
  "http://localhost:8080/realms/master/protocol/openid-connect/token" \
  -d "grant_type=password&client_id=admin-cli" \
  -d "username=${KC_ADMIN}&password=${KC_ADMIN_PASSWORD}" | \
  jq -r '.access_token')

# Verificar que los realms existen
curl -s -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "http://localhost:8080/admin/realms" | jq '.[].realm'

# Verificar número de usuarios por realm
curl -s -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "http://localhost:8080/admin/realms/realm-internal/users/count"

Paso 7 — Levantar el resto de servicios¶

docker compose up -d traefik
docker compose up -d  # El resto de aplicaciones

# Verificar estado de todos los contenedores
docker compose ps

Paso 8 — Smoke tests de validación¶

KC_URL="https://${KC_HOSTNAME}"

# Discovery endpoint
curl -sf "${KC_URL}/realms/realm-internal/.well-known/openid-configuration" | \
  jq '.issuer' && echo "Discovery OK"

# Obtener token con client credentials
TOKEN=$(curl -s -X POST \
  "${KC_URL}/realms/realm-partners/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=partner-service-m2m" \
  -d "client_secret=${M2M_CLIENT_SECRET}" | \
  jq -r '.access_token')

[ "$TOKEN" != "null" ] && echo "Token M2M OK" || echo "ERROR: Token M2M falló"

# Health de aplicaciones
curl -sf http://localhost:8081/actuator/health | jq .status

Checklist de validación post-restore¶

PostgreSQL: contenedor Up (healthy)
Keycloak: contenedor Up (healthy), /health/ready devuelve {status: UP}
Traefik: contenedor Up, dashboard accesible
Discovery endpoint devuelve JSON válido para cada realm
Login con usuario de prueba funciona en la consola admin
Token M2M obtenido con éxito
APIs protegidas responden correctamente con token válido
Número de usuarios por realm coincide con lo esperado

Tiempos estimados¶

Operación	Tiempo estimado
Verificar backup	2 min
Restaurar PostgreSQL (DB ~500 MB)	5-10 min
Levantar Keycloak	1-2 min
Smoke tests	5 min
Total	~20 min

Probar el restore antes de un incidente real

Realiza una restauración de prueba en un VPS de staging al menos una vez al mes. El procedimiento documentado puede tener gaps si no se prueba regularmente.

No sobreescribir un sistema en producción sin detenerlo

Antes de restaurar la base de datos, detén Keycloak para evitar escrituras concurrentes que corrompan la restauración.