00 Configuración

Crea los servicios en la nube, instala los clientes locales, conecta tu agente una vez e inicia la aplicación local.

Los comandos de esta página usan los valores guardados en .env.workshop.

Elige macOS o Windows en el encabezado de la página antes de empezar. La selección se conserva durante todo el taller. En Windows se usa Ubuntu con WSL 2, por lo que los mismos comandos de Bash, Docker, ClickHouse y del agente funcionan en todos los módulos.

Resultado

En unos 25 minutos, tendrás:

un servicio ClickHouse Cloud y una clave de API de la organización;
clickhousectl y el cliente de base de datos clickhouse;
skills de ClickHouse y conexiones MCP de ClickHouse y ClickStack en tu agente de programación;
claves de Langfuse y OpenAI;
la aplicación en buen estado en localhost:8080.

Los endpoints de ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse y MCP están alojados en la nube. Solo la aplicación del taller, las herramientas de CLI y cliente, el agente de programación, el generador de carga y el recolector de telemetría sin estado se ejecutan en tu equipo.

Después del paso 2, ejecuta todos los comandos desde el directorio de la aplicación, salvo que un paso indique lo contrario.

Paso 1: comprueba los requisitos previos

Necesitas Docker con al menos 6 GB de memoria, Git, Node.js 22+, Python 3 y un agente de programación compatible con MCP: Claude Code, Cursor, Codex CLI o Windsurf.

Configuración de macOS

Instala Docker Desktop para Mac y asigna al menos 6 GB en Settings -> Resources. Abre Terminal y ejecuta:

docker version
docker compose version
git --version
node --version
python3 --version

Continúa solo cuando todos los comandos muestren una versión y docker version incluya las secciones Client y Server.

¿Portátil administrado?

La política corporativa puede bloquear la instalación de MCP o el OAuth en el navegador. Usa un equipo personal o consulta al administrador si no se puede abrir el paso de OAuth del paso 7.

Paso 2: clona el repositorio y cambia al branch del taller

Ejecuta lo siguiente en Terminal de macOS:

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

Mantén esta terminal en ClickHouse_Demos/workshops/build_workshop/app. En Windows, esto significa usar la terminal de Ubuntu. El script de comprobación previa es ./preflight.sh dentro de este directorio. Permanece en build-workshop-v1, salvo durante las pruebas de fallos del módulo 07. Confirma ahora el branch:

git branch --show-current

Resultado esperado: build-workshop-v1.

Paso 3: crea una cuenta y una clave de API de ClickHouse Cloud

Antes del día del taller: crea las tres cuentas

Si vas a asistir a un taller programado, crea de antemano tus cuentas de ClickHouse Cloud, Langfuse y OpenAI. Cada registro puede tardar entre 5 y 10 minutos debido a la verificación por correo electrónico o teléfono. Vuelve aquí durante la configuración para crear las claves y los recursos utilizados en los ejercicios.

Formación presencial: usa la clave de API de organización de ClickHouse Cloud específica para el participante, proporcionada de forma segura por el instructor, y omite este paso.

Inicia sesión o comienza una prueba en console.clickhouse.cloud.
Abre API Keys, crea una clave de organización Admin y guarda su Key ID y secreto.

El secreto solo se muestra una vez. Guárdalo fuera del repositorio; no lo incluyas en .env.workshop.

Paso 4: instala `clickhousectl`

curl https://clickhouse.com/cli | sh
export PATH="$HOME/.local/bin:$PATH"
clickhousectl --version

Añade ~/.local/bin al perfil del shell si una terminal nueva no encuentra clickhousectl. En Windows, instálalo y ejecútalo dentro de Ubuntu; no uses un ejecutable de Windows en PowerShell.

Paso 5: autentica `clickhousectl`

Usa la clave de API del paso 3. El modo interactivo mantiene el secreto fuera del historial del shell:

clickhousectl cloud auth login --interactive

Una automatización de confianza puede usar el formato explícito que espera la CLI:

clickhousectl cloud auth login --api-key <key> --api-secret <secret>

Verifica tanto las credenciales guardadas como el acceso a Cloud:

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl guarda las credenciales del proyecto en .clickhouse/, dentro del directorio actual. Sigue ejecutando los comandos de Cloud desde el directorio de la aplicación y nunca añadas ni compartas esa carpeta.

Paso 6: crea el servicio ClickHouse

Elige la región que también utilizarás para Postgres en el módulo 03. Sustituye la región del ejemplo si es necesario:

clickhousectl cloud service create \
  --name my-workshop-clickhouse \
  --provider aws \
  --region ap-southeast-1 \
  --min-replica-memory-gb 8 \
  --max-replica-memory-gb 8 \
  --num-replicas 1 \
  --idle-scaling true \
  --idle-timeout-minutes 15

Guarda el service ID y la default-user password de un solo uso que se devuelven. Comprueba la disponibilidad:

clickhousectl cloud service list
clickhousectl cloud service get <service-id>

Instala un cliente de la misma versión principal y secundaria que el servicio en la nube. Esto evita los avisos de configuración desconocida que un cliente stable más reciente puede emitir contra un servidor en la nube algo más antiguo:

CLICKHOUSE_VERSION=$(clickhousectl cloud service query \
  --id <service-id> \
  --format TabSeparatedRaw \
  --query "SELECT version()")
CLICKHOUSE_SERIES=$(printf '%s\n' "$CLICKHOUSE_VERSION" | cut -d. -f1,2)
clickhousectl local use "$CLICKHOUSE_SERIES"
clickhouse client --version

local use solo instala un binario cliente; no inicia ningún servidor ClickHouse. Todas las consultas del taller se dirigen a ClickHouse Cloud. Desde el cuadro de diálogo Connect del servicio, copia el nombre de host y verifica el cliente. La opción --password solicita la contraseña sin mostrarla:

cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app"
workshop_env() { sed -n "s/^$1=//p" .env.workshop | tail -n 1; }
CLICKHOUSE_HOST=$(workshop_env CLICKHOUSE_HOST)
CLICKHOUSE_USER=$(workshop_env CLICKHOUSE_USER)
CLICKHOUSE_PASSWORD=$(workshop_env CLICKHOUSE_PASSWORD)
unset -f workshop_env

clickhouse client \
  --host "$CLICKHOUSE_HOST" \
  --secure \
  --user "$CLICKHOUSE_USER" \
  --password "$CLICKHOUSE_PASSWORD" \
  --query "SELECT version(), currentUser()"

Resultado esperado: una fila con la versión de ClickHouse y default.

Paso 7: configura una sola vez las skills del agente y ambos servidores MCP

Estas integraciones tienen funciones diferentes:

Integración	Finalidad	Se usa en
Skills de ClickHouse	Revisar el esquema y el SQL según las prácticas de ClickHouse	Módulos 01 y 03
ClickHouse MCP (`/mcp`)	Leer tu servicio mediante consultas `SELECT`	Módulos 01 y 04
ClickStack MCP (`/clickstack`)	Buscar en la telemetría y guardar artefactos de SRE	Módulos 06 y 07

Primero instala las skills para tu agente:

clickhousectl skills --agent <claude|cursor|codex|windsurf>

En ClickHouse Cloud, abre el cuadro de diálogo Connect de tu servicio y habilita Connect with MCP. Después, añade ambos endpoints y completa el OAuth en el navegador:

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp
claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack
claude mcp login clickhouse-cloud
claude mcp login clickstack

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp
codex mcp add clickstack --url https://mcp.clickhouse.cloud/clickstack
codex mcp login clickhouse-cloud
codex mcp login clickstack

Añade esto una vez a .cursor/mcp.json y autoriza ambos servidores en la configuración de Cursor:

{
  "mcpServers": {
    "clickhouse-cloud": { "url": "https://mcp.clickhouse.cloud/mcp" },
    "clickstack": { "url": "https://mcp.clickhouse.cloud/clickstack" }
  }
}

Añade esto una vez a ~/.codeium/windsurf/mcp_config.json y autoriza ambos servidores:

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    },
    "clickstack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/clickstack"]
    }
  }
}

Verifica ahora la conexión con ClickHouse:

Use the clickhouse-cloud MCP to list my databases. Run read-only queries only.

Es normal que ClickStack no devuelva resultados hasta que el módulo 05 envíe telemetría. No repitas la configuración de MCP más adelante; los módulos 06 y 07 usan la conexión clickstack configurada aquí.

Paso 8: crea las claves de Langfuse y OpenAI

Langfuse registra los traces del chat con IA que se utilizan en el módulo 08.

Formación presencial: usa la clave de API del proyecto de OpenAI específica para el participante, proporcionada de forma segura por el instructor, y omite el punto 3. Aún necesitas las claves de Langfuse de los puntos 1 y 2.

Crea un proyecto en Langfuse Cloud de EE. UU. o en Langfuse Cloud de la UE.
Crea un par de claves de API de proyecto y guarda las claves pública y secreta.
Crea una clave de API limitada al proyecto en platform.openai.com/api-keys y habilita la facturación.

Usa la URL de Langfuse de la región en la que hayas creado el proyecto:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

OPENAI_API_KEY=sk-...

Conserva los valores predeterminados del modelo y la base de la API que ya contiene .env.workshop.

Paso 9: rellena `.env.workshop`

Copia los valores del servicio del paso 6 y las claves del paso 8 en los campos existentes:

CLICKHOUSE_HOST=<hostname without https:// or port>
CLICKHOUSE_PORT=8443
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=<one-time service password>
CLICKHOUSE_DATABASE=nyc_tlc_data
CLICKHOUSE_SECURE=true

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
OPENAI_API_KEY=sk-...

No exportes estos nombres en el shell: los valores exportados prevalecen sobre el archivo de entorno.

Paso 10: ejecuta la comprobación previa e inicia la aplicación

Los comandos siguientes abren el directorio correcto desde cualquier punto del repositorio clonado:

cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app"
./preflight.sh

Continúa solo cuando la última línea sea Overall: READY. Aplica cualquier corrección que se indique y vuelve a ejecutar el script. A continuación, inicia la pila:

docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d --build
docker compose --env-file .env.workshop -f docker-compose.workshop.yml ps

En unos dos minutos, los contenedores locales backend y frontend de la aplicación deberían indicar healthy, y la aplicación debería abrirse en localhost:8080. No se inicia ningún servidor de base de datos localmente. Los paneles vacíos son correctos hasta el módulo 01.

Comprobación final

clickhousectl cloud service get <service-id> indica que el servicio está listo.
clickhouse client ... --query "SELECT version()" funciona correctamente.
Tu agente enumera las bases de datos mediante ClickHouse MCP.
./preflight.sh termina con Overall: READY desde el directorio de la aplicación.
Los servicios de Docker están en buen estado y la aplicación local se carga.

Continúa en 01 ClickHouse Cloud.