Levantar el ambiente de desarrollo

Qué vas a levantar

El backend de WL no es un único servidor — es un ecosistema de microservicios que corren dentro de un cluster de Kubernetes local. Para manejarlo, el equipo usa Tilt, una herramienta que observa tu código, detecta cambios y recarga los servicios automáticamente.

No necesitas saber Kubernetes para trabajar aquí. Tilt lo abstrae. Tu trabajo es editar código; Tilt se encarga del resto.

Puntos de acceso principales:

• Tilt Dashboard → http://localhost:10350 — panel de control: logs, estado de servicios, reinicios
• BFF (API principal) → http://localhost:3000 — el punto de entrada al backend

---

Clonar el repositorio

Este es el punto de partida. Clona el repositorio principal y entra a la carpeta — todos los make commands de esta guía se corren desde ahí.

git clone [email protected]:Cencosud-Cencommerce/dc-wl-groceries-backend.git
cd dc-wl-groceries-backend

---

Prerrequisitos

Antes de empezar, necesitas tener instalado:

1. Rancher Desktop → rancherdesktop.io

Incluye Docker y kubectl. Es el motor que corre el cluster de Kubernetes local. Después de instalarlo, asegúrate de que esté corriendo antes de continuar.

2. Go → golang.org/dl

Los microservicios y las herramientas de desarrollo están escritos en Go. El equipo usa siempre la última versión estable. Verifica la tuya:

go version

Si tienes Go < 1.22 o no lo tienes instalado, descarga la versión más reciente desde golang.org/dl.

3. SSH key configurada en GitHub

El proyecto usa un paquete Go privado de la organización. Necesitas tener tu SSH key en GitHub con acceso a la org Cencosud-Cencommerce.

Si todavía no tienes una SSH key, genérala así:

# Generar la key (reemplaza con tu email de trabajo)
ssh-keygen -t ed25519 -C "[email protected]"

# Muestra la clave pública para copiarla
cat ~/.ssh/id_ed25519.pub

Pega el resultado en github.com/settings/keys → New SSH key.

Para verificar que funciona:

ssh -T [email protected]
# Respuesta esperada: Hi <usuario>! You've successfully authenticated...

Si el acceso a la organización aún no está habilitado, pídelo a tu tech lead — es una aprobación que hacen desde GitHub.

Tilt se instala automáticamente durante el setup — no necesitas instalarlo manualmente.

---

Acceso a paquetes privados de Go

El proyecto tiene una dependencia en un paquete privado: github.com/Cencosud-Cencommerce/dc-wl-groceries-shared-pkg. Configura esto antes de correr make init — el init descarga dependencias Go y sin esta configuración falla con errores crípticos sobre módulos no encontrados.

Ejecuta estos comandos una sola vez:

# Decirle a Git que use SSH en lugar de HTTPS para GitHub
git config --global --add url."[email protected]:".insteadOf "https://github.com/"

# Decirle a Go que este paquete es privado (no buscar en el proxy público)
export GOPRIVATE="github.com/Cencosud-Cencommerce/*"

# Persistir la variable en tu shell para que aplique siempre
echo 'export GOPRIVATE="github.com/Cencosud-Cencommerce/*"' >> ~/.zshrc
source ~/.zshrc

---

Inicialización (solo la primera vez)

1. Clonar e inicializar todo

make init

Este comando hace todo de una vez:

make init
    │
    ├─ Verifica que Docker esté instalado (Rancher Desktop)
    ├─ Verifica que kubectl esté disponible
    ├─ Verifica que Go esté instalado
    ├─ Instala Tilt.dev automáticamente
    ├─ Clona todos los repositorios de microservicios → services/
    └─ Configura el Go workspace (go.work)

Al terminar, tu proyecto tendrá esta estructura:

dc-wl-groceries-backend/
├── Makefile
├── dc-wl-groceries-backend.code-workspace   ← workspace de VS Code
├── go.work                                   ← Go workspace (une todos los módulos)
├── k8s.local/
│   └── key.json        ← colócalo aquí (ver sección siguiente)
├── services/           ← creado por make init, contiene todos los repos
│   ├── app-bff/
│   ├── customers/
│   ├── cart/
│   └── ...
└── .env                ← opcional, para elegir el tenant activo

2. Instalar herramientas de desarrollo

make tools

Este comando instala las herramientas necesarias para el desarrollo activo: generadores de código a partir de .proto, herramientas de migración de base de datos y el linter de Go.

Lo que instala:

Herramienta	Para qué sirve
protoc-gen-go, protoc-gen-go-grpc	Generar código Go a partir de Protobuf
protoc-gen-grpc-gateway, protoc-gen-openapiv2	Generar gateway HTTP y specs OpenAPI
buf	Build tool para Protobuf
grpcurl	Hacer llamadas gRPC desde la terminal (como curl pero para gRPC)
migrate	Migraciones de base de datos
sqlc	Generar código Go type-safe a partir de SQL
golangci-lint	Linter de Go

---

Credenciales GCP

El ambiente usa External Secrets Operator para cargar credenciales de APIs externas (Cognito, Auth0, VTEX, etc.) desde Google Cloud Secret Manager. Sin este archivo, el ambiente levanta pero los servicios fallan silenciosamente al intentar conectarse a servicios externos.

Qué necesitas: un archivo key.json con las credenciales de una service account de GCP.

Cómo obtenerlo: pídele el archivo a tu tech lead.

Dónde colocarlo:

dc-wl-groceries-backend/
└── k8s.local/
    └── key.json   ← aquí

El archivo se carga automáticamente cuando ejecutas make up. Está en .gitignore — nunca se commitea.

---

Los tenants

El backend WL es multi-tenant: el mismo código corre para distintos supermercados (Jumbo Argentina, Disco, Total Fresh Market, etc.). Localmente, se levanta un solo tenant a la vez y se controla con la variable FLAG en el archivo .env.

Cómo configurarlo: crea un archivo .env en la raíz del proyecto y descomenta el tenant que quieres usar:

# FLAG=ar-jumbo      # Jumbo Argentina
# FLAG=ar-disco      # Disco Argentina
# FLAG=co-jumbo      # Jumbo Colombia
FLAG=us-tfm          # Total Fresh Market US
# FLAG=br-prezunic   # Prezunic Brasil

Si no hay archivo .env, el sistema usa ar-jumbo por defecto.

---

Levantar el ambiente

Con los prerrequisitos listos y el key.json en su lugar:

make up

Este comando crea el namespace de Kubernetes y arranca Tilt. La primera vez puede tardar varios minutos mientras descarga las imágenes. Las veces siguientes es mucho más rápido.

Qué esperar:

1. Tilt inicia y abre el stream de logs en la terminal
2. Accede al dashboard: http://localhost:10350
3. En el dashboard verás todos los servicios con su estado (verde = corriendo, amarillo = iniciando, rojo = error)
4. Cuando app-bff está verde, el ambiente está listo

En el dashboard puedes:

• Ver los logs de cada servicio en tiempo real
• Reiniciar un servicio individual con un click
• Ver el historial de builds y deploys

Servicios de infraestructura disponibles:

Servicio	URL	Para qué
Tilt Dashboard	http://localhost:10350	Panel de control general
BFF	http://localhost:3000	API principal
Jaeger UI	http://localhost:16686	Trazas distribuidas
Redis Insight	http://localhost:5540	Gestión visual de Redis
MongoDB	mongodb://localhost:27017	Base de datos NoSQL

---

Tu primera petición

Con app-bff verde en el dashboard, el ambiente está operativo. Verifícalo con una petición real:

curl http://localhost:3000/health

También puedes abrirlo directo en el browser: http://localhost:3000/health. Si el BFF levantó bien, la respuesta será 200 OK.

Explora la API completa:

Abre http://localhost:3000/docs en el browser. Ahí encontrarás la documentación Swagger interactiva del BFF — todos los endpoints documentados, con la posibilidad de hacer peticiones directamente desde la UI sin necesidad de Postman ni curl.

---

Workflow del día a día

# Inicio del día: levantar el ambiente
make up

# Fin del día: detener sin perder datos
make stop

# Actualizar todos los repos al último main
make main

---

Debugging con VS Code

Todos los microservicios Go corren con Delve embebido y exponen un puerto de debugging remoto. Desde VS Code puedes conectarte, poner breakpoints y ejecutar paso a paso como si el servicio corriera localmente.

Abrir el workspace

El proyecto incluye un workspace de VS Code preconfigurado con todas las carpetas de microservicios y las configuraciones de debug listas:

code dc-wl-groceries-backend.code-workspace

Puertos de debug por servicio

Servicio	Puerto	Tipo
app-bff	40000	Go (Delve)
customers	40001	Go (Delve)
cart	40003	Go (Delve)
carts	40004	Go (Delve)
search	40005	Go (Delve)
engine-promotions	40006	Go (Delve)
notifications	40008	Go (Delve)
products	40011	Go (Delve)
coupons	40012	Go (Delve)
recommendations	40013	Go (Delve)
loyalty	40014	Go (Delve)
auth	40015	Go (Delve)
session-manager	9229	Node.js Inspector

Conectarse a un servicio Go

1. Asegúrate de que el ambiente esté corriendo (make up)
2. En VS Code, abre el panel Run and Debug (Ctrl+Shift+D o Cmd+Shift+D)
3. En el dropdown de configuraciones, selecciona el servicio (ej: app-bff)
4. Presiona F5 para conectarte
5. Pon breakpoints en el código del servicio — VS Code los va a interceptar

El servicio sigue corriendo normalmente; el debugger se adjunta sin reiniciarlo.

Conectarse a session-manager (Node.js)

El servicio session-manager usa Node Inspector en lugar de Delve. El proceso es el mismo: selecciona session-manager en el dropdown y presiona F5. Compatible con Chrome DevTools también.

---

Referencia de comandos

Setup inicial (solo la primera vez)

Comando	Qué hace
make init	Verifica prerrequisitos + clona repos + configura go.work
make setup	Solo verifica prerrequisitos e instala Tilt
make clone	Solo clona los repositorios de servicios
make tools	Instala herramientas de desarrollo Go

Ciclo de vida del ambiente

Comando	Qué hace
make up	Levanta el ambiente completo con Tilt
make us-tfm	Levanta el ambiente con servicios específicos de US TFM
make stop	Detiene Tilt — preserva datos y PVCs
make down	⚠️ Detiene Tilt y destruye namespace + borra todos los datos

Mantenimiento

Comando	Qué hace
make main	Actualiza todos los repos al último commit de main
make cleanup	⚠️ Borra la carpeta services/ — requiere re-clonar con make clone
make clean	⚠️ Limpieza total de Docker: elimina imágenes, contenedores y volúmenes

---

Problemas comunes

go.mod file not found al hacer build

Los repos no están clonados. Ejecuta make clone para descargarlos.

kubectl not found o docker not found

Rancher Desktop no está instalado o no está corriendo. Instálalo desde rancherdesktop.io y asegúrate de que esté activo antes de continuar.

Los servicios levantan pero fallan al conectarse a APIs externas

Falta el key.json. Coloca el archivo en k8s.local/key.json y reinicia con make stop && make up.

El namespace no existe: Error from server (NotFound): namespaces "dc-wl-groceries" not found

Ocurre si ejecutaste make down antes. make up lo recrea automáticamente.

El cluster crashea frecuentemente

Aumenta los recursos asignados a Rancher Desktop: mínimo 4 CPU cores y 8 GB de RAM. Configúralo desde las preferencias de Rancher Desktop.

Puerto de debug ya en uso

Hay otra instancia corriendo. Detén el ambiente primero con make stop. Si el puerto sigue ocupado:

# Reemplaza 40000 por el puerto del servicio que quieres depurar
lsof -ti:40000 | xargs kill -9