Laboratorio — Entorno de trabajo

Todo el trabajo práctico del curso (laboratorios, Tinkuy y el proyecto) se hace con las mismas herramientas para todos: un contenedor Docker que trae Node.js, PostgreSQL, Redis, NATS y las herramientas de medición del curso. Así evitamos el “en mi computadora sí funciona”: si make check pasa en el contenedor, pasa en la revisión.

En este curso el entorno importa más que en otros, porque casi todos los laboratorios miden algo (latencia, throughput, errores) o rompen algo a propósito (matar un servicio, cortar la red). Las dos cosas se hacen dentro del contenedor, sin tocar su computadora.

1. Requisitos

Sistema Qué instalar
Linux Docker Engine y Git
Windows 10/11 WSL2 + Docker Desktop con integración WSL, y Git dentro de WSL. Trabajen dentro del sistema de archivos de WSL (~/), no en C:\.
macOS (Intel o Apple Silicon) Docker Desktop y Git (viene con las herramientas de línea de comandos de Xcode)

Además, un editor (VS Code o el que prefieran). La imagen es nativa: en una laptop ARM (Apple Silicon) corre como ARM y en una Intel o AMD como x86-64, sin emulación. Denle a Docker al menos 4 GB de memoria.

2. Levantar el contenedor

Desde la carpeta del curso:

./env/run.sh                 # la primera vez construye la imagen (unos minutos)

run.sh monta el directorio actual en /work: los archivos se editan con el editor de siempre en su computadora y se ejecutan en el contenedor. El puerto 3000 del contenedor queda publicado en http://localhost:3000. También acepta un comando:

./env/run.sh make test           # corre las pruebas de la carpeta actual
./env/run.sh --rebuild           # reconstruye la imagen (si cambió el Dockerfile)

Casi todos los laboratorios necesitan varias terminales a la vez: una con el servidor, otra con la pasarela de pagos simulada, otra con la carga. Si el contenedor ya está abierto, ./env/run.sh en otra terminal abre una segunda shell en el mismo contenedor, con los mismos servicios y los mismos datos.

Los datos viven dentro del contenedor: cuando se cierra la última terminal, se pierden. Es a propósito: cada laboratorio crea los suyos con make db o con el make de su carpeta, y nadie arrastra el estado de la semana anterior.

3. Qué trae el contenedor

Herramienta Para qué Semanas
Node.js 26 Ejecuta TypeScript directamente: node src/main.ts todas
node --test Runner de pruebas de Node (node:test, node:assert/strict) todas
tsc (TypeScript 6) Revisa los tipos: tsc --noEmit todas
dependency-cruiser (depcruise) Comprueba las reglas de dependencias entre módulos 3, 4, 15
PostgreSQL 18 (psql) La base de datos de Tinkuy; con pg-replica, una réplica todas; 10
Redis (redis-cli) Cache 6, 11
NATS con JetStream (nats) Mensajería: streams y consumers 5, 13
k6 Pruebas de carga con umbrales 2, 6, 11, 12, 14, 15
Toxiproxy (toxiproxy-cli) Fallas de red a pedido: latencia, cortes 14, 15

Los paquetes de npm del curso (pg, redis, nats) están instalados en la imagen: un import pg from 'pg' funciona en cualquier carpeta sin npm install. En el curso no se descarga nada con npm.

4. Los servicios

PostgreSQL, Redis y NATS arrancan con el contenedor. El comando svc los controla:

svc status                # qué está corriendo
svc start toxiproxy       # inicia un servicio (Toxiproxy no arranca solo)
svc stop redis            # lo detiene de forma ordenada
svc kill redis            # lo mata sin aviso, como en una caída real
svc start redis           # lo vuelve a levantar

Con todo recién levantado, svc status responde:

postgres: arriba
redis: arriba
nats: arriba
toxiproxy: detenido
Servicio Puerto Cómo conectarse
PostgreSQL 5432 psql (sin contraseña, usuario postgres); desde Node, new pg.Pool() sin argumentos
Réplica de PostgreSQL 5433 psql -p 5433; solo existe después de pg-replica create
Redis 6379 redis-cli; desde Node, createClient()
NATS 4222 (monitoreo en 8222) nats; desde Node, connect({ servers: '127.0.0.1:4222' })
Toxiproxy 8474 (su API) toxiproxy-cli

Los logs de cada servicio están en /var/log/course/.

La réplica de PostgreSQL se usa en la semana 10 y en P3:

pg-replica create         # copia el principal y arranca la réplica en el puerto 5433
pg-replica lag            # cuánto le falta aplicar
pg-replica stop | start   # la detiene y la vuelve a iniciar
pg-replica promote        # la convierte en principal
pg-replica destroy        # la borra

Para no pisarse entre semanas, cada laboratorio usa su propia base de datos (arq_wNN), su prefijo de claves en Redis (wNN:) y su prefijo de streams en NATS (WNN_). Los Makefile de cada semana ya lo hacen.

5. Tinkuy

tinkuy/ es el sistema de venta de entradas escrito para el curso: el ejemplo de los laboratorios y el punto de partida del proyecto. Su README describe los endpoints y la estructura.

cd tinkuy
make db           # crea la base de datos y carga los datos de ejemplo
make gateway      # la pasarela de pagos simulada, en el puerto 4000 (una terminal)
make start        # el servidor, en http://localhost:3000 (otra terminal)
make check        # tipos y pruebas

Para los laboratorios trabajen sobre una copia de Tinkuy en su propio repositorio, no en la carpeta del curso. Clonen su repositorio dentro de la carpeta del curso (el .gitignore del curso ignora las carpetas tinkuy-* y equipo-*) y abran el contenedor desde la carpeta del curso: así, dentro, el material está en /work y su copia en /work/tinkuy-suusuario.

6. Medir

Las mediciones del curso se hacen con k6. Tres reglas, que valen para todos los laboratorios y para el proyecto:

  1. Percentiles, no promedios. Se reportan p50, p95 y, si hay suficientes muestras, p99, junto con el throughput y la tasa de errores.
  2. Se compara en la misma máquina. Un número suelto no dice nada: depende de la laptop, de cuánta memoria tiene Docker y de qué más está corriendo. Lo que se reporta es la comparación entre dos diseños, medidos uno después del otro en la misma máquina, y se dice cuál es.
  3. Más de una corrida. Antes de afirmar que un cambio mejoró algo, se repite la medición y se mira cuánto varía entre corridas sin cambiar nada.

Cierren lo que no usen mientras miden, y partan siempre de datos recién cargados (make db): una base de datos con las ventas de la corrida anterior no se comporta igual.

7. Git

Git funciona igual en su computadora y en el contenedor. run.sh monta su ~/.gitconfig (solo lectura), así que los commits hechos dentro del contenedor llevan su nombre y su correo. Para subir y traer cambios (git push, git pull), usen la terminal de su computadora, donde ya tienen sus credenciales: el contenedor no las guarda.

8. Solución de problemas

Síntoma Causa probable
Cannot connect to the Docker daemon Docker Desktop no está abierto.
svc status muestra un servicio detenido que debería estar arriba Se cayó o lo mataron en un laboratorio. svc start <servicio> y revisen /var/log/course/<servicio>.log.
ECONNREFUSED 127.0.0.1:4000 al comprar La pasarela simulada no está corriendo: make gateway en otra terminal.
database "tinkuy" does not exist El contenedor es nuevo y todavía no corrieron make db.
sorry, too many clients already Se agotaron las conexiones de PostgreSQL. En el Tinkuy inicial pasa bajo carga, y es parte de lo que el curso estudia (semana 6).
EADDRINUSE en el puerto 3000 o 4000 Ya hay un servidor corriendo en otra terminal del contenedor.
El programa termina su trabajo y no devuelve la terminal Quedó una conexión abierta: falta pool.end(), client.quit() o nc.drain().
pg-replica create dice que la réplica ya existe Quedó de un laboratorio anterior en este mismo contenedor: pg-replica destroy.
Las mediciones cambian mucho entre corridas Otra cosa compite por la máquina, o Docker tiene poca memoria. Cierren aplicaciones y repitan.
En Windows todo es muy lento El repositorio está en C:\ y no en el sistema de archivos de WSL.