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:
- Percentiles, no promedios. Se reportan p50, p95 y, si hay suficientes muestras, p99, junto con el throughput y la tasa de errores.
- 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.
- 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. |