Prerequisitos

Objetivo de este módulo: en veinte minutos tienes el entorno listo, un límite de gasto configurado, y tu propio repositorio con el código base.

Primero, dónde vas a trabajar

El taller funciona igual en los tres sistemas, pero en Windows hay que elegir bien la terminal. Busca tu caso y sigue solo esa pestaña.

Windows

Instala Docker Desktop con el backend de WSL2, y trabaja siempre dentro de WSL2, no en PowerShell ni en CMD.

1. Instala WSL2 con Ubuntu, desde PowerShell como administrador:

   wsl --install -d Ubuntu

2. Instala Docker Desktop y, en Settings → General, confirma que está marcado Use the WSL 2 based engine. En Settings → Resources → WSL integration, habilita tu distribución de Ubuntu.

3. Abre la terminal de Ubuntu, no PowerShell, y comprueba que ves el demonio:

   docker info --format '{{.ServerVersion}}'

Trabaja en el disco de Linux, no en /mnt/c

Crea la carpeta del taller en tu home de Ubuntu (~/protecso-workshops), no en /mnt/c/Users/....

Los dos son accesibles desde WSL2, pero /mnt/c cruza la frontera entre sistemas de archivos en cada lectura. Con un node_modules de miles de archivos, npm ci y el arranque de Vite pasan de segundos a minutos. Es la causa número uno de “el taller me va lentísimo” en Windows.

Por qué WSL2 y no PowerShell

Los dos repositorios del taller traen un Makefile, y make y bash no existen en Windows nativo. Con Git Bash tampoco alcanza: al montar volúmenes, las rutas estilo /c/Users/... se traducen mal y Docker monta directorios vacíos, sin dar ningún error. Dentro de WSL2 todo eso desaparece porque ya es Linux.

Linux

Instala Docker Engine desde los paquetes de tu distribución y agrégate al grupo docker para no escribir sudo en cada comando:

sudo usermod -aG docker $USER
newgrp docker
docker info --format '{{.ServerVersion}}'

No hay nada más que ajustar. Los Makefile del taller detectan que estás en Linux y le pasan tu identificador de usuario al contenedor, así que los archivos que se creen en tus repositorios quedan siendo tuyos y no de root.

macOS

Cualquiera de las tres opciones sirve: Docker Desktop, OrbStack o Colima.

docker info --format '{{.ServerVersion}}'

Lo único que instalas

git y docker. Nada más.

Node, Terraform, la AWS CLI y gh vienen en una imagen de contenedor, con versiones fijas. Así todos en la sala usan exactamente lo mismo y desaparece la media hora que normalmente se pierde en “a mí me da otro error”.

1. Verifica lo que ya tienes:

   git --version
   docker --version
   docker info --format '{{.ServerVersion}}'

   El tercero es el importante: confirma que el demonio está corriendo, no solo que el cliente está instalado.

2. Trae la imagen del taller:

   docker pull ghcr.io/protecso-sac/workshop-toolchain:v1

3. Comprueba que trae todo:

   docker run --rm ghcr.io/protecso-sac/workshop-toolchain:v1 \
     bash -c 'node -v && terraform version | head -1 && aws --version && gh --version | head -1'

   Deberías ver Node 24, Terraform 1.16.1, AWS CLI 2 y gh 2.

Cómo se usa el contenedor

La idea es montar tu carpeta de trabajo dentro del contenedor. Dentro tienes Node, Terraform, la AWS CLI, gh, git y make.

Empieza creando la carpeta donde va a vivir todo el taller:

mkdir -p ~/protecso-workshops
cd ~/protecso-workshops

Y define este alias en tu terminal. Es el contenedor con tu carpeta de trabajo, tu perfil de AWS y tu sesión de gh montados:

alias taller='docker run --rm -it \
  -u $(id -u):$(id -g) -e HOME=/tmp \
  -v "$PWD":/work -w /work \
  -v "$HOME/.aws":/tmp/.aws \
  -v "$HOME/.config/gh":/tmp/.config/gh \
  -e AWS_PROFILE -e AWS_REGION -e GH_TOKEN \
  ghcr.io/protecso-sac/workshop-toolchain:v1'

Por qué el -u y el HOME en /tmp

El contenedor corre con tu identificador de usuario, así que todo lo que escriba en tu carpeta queda siendo tuyo. Sin eso, en Linux los archivos aparecerían como de otro dueño y tendrías que arreglarlos con sudo a mitad del taller.

El efecto secundario es que el HOME de la imagen deja de ser escribible para tu usuario, y por eso la configuración se monta bajo /tmp, que sí lo es. Los Makefile de los dos repositorios hacen exactamente lo mismo.

Después no lo vas a necesitar

Los dos repositorios del taller traen un Makefile que envuelve exactamente este patrón, así que en cuanto los tengas clonados escribes comandos cortos:

make help      # lista lo que puedes hacer en ese repositorio
make shell     # la misma terminal del contenedor
make dev       # en el repo de la app: servidor de desarrollo
make plan      # en el repo de infra: plan de Terraform

El alias te sirve ahora, cuando todavía no tienes ningún repositorio.

Autenticar gh dentro del contenedor

gh vive en el contenedor, no en tu máquina. Como el contenedor se destruye al salir, la sesión se guarda en tu host, en ~/.config/gh, y se vuelve a montar la próxima vez. Te autenticas una sola vez.

1. Crea el directorio de configuración en el host y entra al contenedor:

   mkdir -p ~/.config/gh
   taller bash

2. Autentícate. Elige GitHub.com, protocolo HTTPS, y responde que sí a autenticar Git con tus credenciales de GitHub:

   gh auth login

   Como no hay navegador dentro del contenedor, gh usa el flujo de dispositivo: muestra un código de ocho caracteres y una URL. Abres esa URL en el navegador de tu máquina, pegas el código, y el contenedor completa el login solo.

3. Comprueba que quedó, y sal:

   gh auth status
   exit

4. Vuelve a entrar y comprueba que la sesión sobrevivió. Esto es lo que confirma que la configuración se está guardando en tu host y no dentro del contenedor:

   taller gh auth status

Por qué HTTPS y no SSH

Al responder que sí a autenticar Git, gh hace el equivalente de gh auth setup-git: configura Git para usar el token de gh como credencial sobre HTTPS.

Con eso, git clone, git push y el push de tags funcionan dentro del contenedor sin montar tus llaves SSH ni reenviar el agente, que en macOS y Windows es una fuente constante de problemas. Y un token guardado en el host es más fácil de revocar que una llave SSH copiada dentro de una imagen.

Si prefieres no usar gh

Todo lo que hace gh en este taller se puede hacer desde la web de GitHub: crear los repositorios, crear los entornos y registrar las variables. La guía muestra las dos formas en pestañas.

En ese caso usa el git de tu máquina para clonar y hacer push, y el contenedor solo para Node, Terraform y la AWS CLI. Funciona igual, solo requiere más clics.

Y si ya administras tus propios tokens, puedes saltarte el login exportando uno antes de entrar:

GH_TOKEN=ghp_xxx make shell

Cuenta de AWS

Necesitas una cuenta con permisos para crear buckets de S3, distribuciones de CloudFront, certificados en ACM y roles de IAM.

Primero, el límite de gasto

Antes de crear nada. Este taller cuesta centavos, pero la costumbre de poner el presupuesto antes de la infraestructura es la que evita sorpresas.

1. En la consola de AWS entra a Billing and Cost Management → Budgets.

2. Crea un presupuesto de costo mensual con un monto bajo, cinco dólares alcanza.

3. Configura una alerta al 80 por ciento con tu correo.

Esto avisa, no frena

Un presupuesto de AWS notifica cuando te acercas al límite, no corta el gasto. No existe un botón de “no me cobres más de esto”. Por eso el módulo de cierre incluye el terraform destroy y una revisión de que no quedó nada corriendo.

Después, las credenciales

Con SSO (recomendado)

aws configure sso
aws sts get-caller-identity

Las credenciales de SSO son temporales, así que no queda una llave de larga duración guardada en tu disco.

Con llave de acceso

aws configure
aws sts get-caller-identity

Si usas una llave de acceso, que sea de un usuario dedicado a este taller y bórrala al terminar. Una llave de larga duración en un archivo es exactamente lo que vamos a evitar en el pipeline más adelante.

El get-caller-identity tiene que responder con tu cuenta y tu identidad. Si falla, no sigas: todo lo demás depende de esto.

Tu identificador en el taller

Elige ahora cómo te vas a llamar durante el taller: tu nombre o tu usuario de GitHub, en minúsculas y sin espacios. Por ejemplo p01.

Ese valor va a nombrar tus recursos de AWS y va a ser tu subdominio en producción, así que apúntalo y no lo cambies después. Tiene que cumplir las reglas de una etiqueta de DNS: minúsculas, números y guiones, sin guión al principio ni al final.

Si te quedas atrás

Va a pasar, y no es un problema. Las plantillas del taller son también el repositorio de soluciones, así que puedes recuperar cualquier archivo tal como debería quedar.

Agrega el remoto una vez, en cada uno de tus dos repositorios:

# en tu repo de la app
git remote add soluciones https://github.com/Protecso-SAC/taskflow-app-template

# en tu repo de infraestructura
git remote add soluciones https://github.com/Protecso-SAC/taskflow-infra-template

Y cuando necesites recuperar algo puntual:

git fetch soluciones
git checkout soluciones/main -- src/lib/reactive.ts

Trae el archivo tal como está en la plantilla

Eso incluye los bloques comentados con marcadores PASO. Si recuperas un archivo donde ya habías descomentado algo, vuelve a descomentarlo.

Y no hagas git checkout soluciones/main -- . sin pensarlo: sobrescribiría todo tu trabajo, incluidos tus terraform.tfvars.

Comprobación final

Con esto deberías tener:

• docker info respondiendo. En Windows, desde la terminal de Ubuntu y con la carpeta del taller en tu home de Linux, no en /mnt/c.
• La imagen de toolchain descargada, con Node, Terraform, AWS CLI y gh.
• gh auth status funcionando desde el contenedor, y sobreviviendo al salir.
• aws sts get-caller-identity devolviendo tu cuenta.
• Un presupuesto con alerta configurado.
• Tu identificador elegido.

Resumen de comandos

mkdir -p ~/protecso-workshops && cd ~/protecso-workshops
mkdir -p ~/.config/gh

docker pull ghcr.io/protecso-sac/workshop-toolchain:v1

# el alias, para antes de tener repositorios
alias taller='docker run --rm -it \
  -u $(id -u):$(id -g) -e HOME=/tmp \
  -v "$PWD":/work -w /work \
  -v "$HOME/.aws":/tmp/.aws \
  -v "$HOME/.config/gh":/tmp/.config/gh \
  -e AWS_PROFILE -e AWS_REGION -e GH_TOKEN \
  ghcr.io/protecso-sac/workshop-toolchain:v1'

taller bash
gh auth login          # GitHub.com, HTTPS, y sí a autenticar Git
gh auth status
exit

taller gh auth status  # comprobar que la sesión sobrevivió
aws sts get-caller-identity

Si todo responde, creamos tus repositorios.