Lab 01 — Instalación y configuración inicial¶

Objetivo: Instalar la plataforma Identity Platform desde cero y verificar que todos los componentes funcionan correctamente.

Duración estimada: 30-45 minutos

Prerrequisitos: - Docker Engine ≥ 24.x instalado - Docker Compose ≥ 2.x instalado - curl, jq disponibles en la terminal - Acceso a internet para descargar imágenes

Paso 1 — Clonar el repositorio¶

git clone https://github.com/tu-org/vps-infrastructure.git
cd vps-infrastructure/apps/keycloak
ls -la

Deberías ver: compose.yml, examples/, docs/

Paso 2 — Configurar variables de entorno¶

# Copiar la plantilla de variables
cp .env.example .env

# Editar las variables
nano .env

Configura al menos estas variables:

# .env — valores para el laboratorio local
KC_HOSTNAME=localhost
KC_ADMIN=admin
KC_ADMIN_PASSWORD=Admin123!
KC_DB_USER=keycloak
KC_DB_PASSWORD=KeycloakDB456!
KC_DB_NAME=keycloak
POSTGRES_PASSWORD=KeycloakDB456!

Estas credenciales son solo para el laboratorio

En un entorno real usa contraseñas generadas aleatoriamente con openssl rand -base64 32.

Paso 3 — Crear las redes Docker¶

# Crear las redes necesarias si no existen
docker network create iam-frontend 2>/dev/null || echo "Red iam-frontend ya existe"
docker network create iam-data 2>/dev/null || echo "Red iam-data ya existe"

# Verificar
docker network ls | grep iam-

Paso 4 — Levantar los servicios¶

# Validar la configuración del compose antes de levantar
docker compose config

# Levantar en segundo plano
docker compose up -d

# Ver los logs en tiempo real
docker compose logs -f

Esperar hasta ver en los logs:

keycloak | Keycloak 26.x... started in XXms
postgres | database system is ready to accept connections

Paso 5 — Verificar el estado de los contenedores¶

docker compose ps

Resultado esperado:

NAME                    STATUS          PORTS
keycloak-postgres-1     Up (healthy)    5432/tcp
keycloak-keycloak-1     Up (healthy)    8080/tcp, 8443/tcp

Si algún contenedor aparece como Restarting o Exit, ver los logs:

docker compose logs keycloak
docker compose logs postgres

Paso 6 — Health checks¶

# PostgreSQL
docker compose exec postgres pg_isready -U keycloak
# Respuesta esperada: /var/run/postgresql:5432 - accepting connections

# Keycloak liveness
curl -sf http://localhost:8080/health/live | jq .
# Respuesta esperada: {"status": "UP"}

# Keycloak readiness
curl -sf http://localhost:8080/health/ready | jq .
# Respuesta esperada: {"status": "UP"}

Paso 7 — Verificar el Discovery endpoint¶

# OpenID Connect Discovery de cada realm
curl -sf \
  http://localhost:8080/realms/master/.well-known/openid-configuration | \
  jq '{issuer, authorization_endpoint, token_endpoint, jwks_uri}'

Resultado esperado:

{
  "issuer": "http://localhost:8080/realms/master",
  "authorization_endpoint": "http://localhost:8080/realms/master/protocol/openid-connect/auth",
  "token_endpoint": "http://localhost:8080/realms/master/protocol/openid-connect/token",
  "jwks_uri": "http://localhost:8080/realms/master/protocol/openid-connect/certs"
}

Paso 8 — Acceder a la Admin Console¶

Abrir en el navegador: http://localhost:8080/admin/
Login con: admin / Admin123!
Explorar la interfaz: Realm Settings, Clients, Users

Paso 9 — Verificar las claves públicas (JWKS)¶

curl -sf http://localhost:8080/realms/master/protocol/openid-connect/certs | \
  jq '.keys[] | {kid, kty, alg, use}'

Deberías ver al menos una clave RSA con "use": "sig".

Checklist de validación¶

docker compose ps muestra todos los contenedores Up (healthy)
pg_isready devuelve accepting connections
/health/live devuelve {"status": "UP"}
/health/ready devuelve {"status": "UP"}
Discovery endpoint devuelve JSON válido con los endpoints correctos
Admin Console accesible en http://localhost:8080/admin/
JWKS endpoint devuelve claves RSA válidas

Troubleshooting¶

Keycloak en loop de restart:

docker compose logs keycloak | grep -E "ERROR|Exception|FATAL"
# Causa común: PostgreSQL no listo cuando Keycloak arranca
docker compose restart keycloak

Puerto 8080 ya ocupado:

lsof -i :8080
# Si hay otro proceso, detenerlo o cambiar el puerto en compose.yml

Error de conexión a la DB:

# Verificar que las variables de entorno son correctas
docker compose exec keycloak env | grep KC_DB

Siguiente paso¶

Una vez verificada la instalación, continúa con Lab 02 — Configuración de Realm y clientes.