🚀 Guía de Configuración y Desarrollo

Esta guía te lleva paso a paso para configurar tu entorno de desarrollo local. La plataforma corre completamente en Docker: basta con clonar los repositorios, poner los archivos de secretos y ejecutar un solo comando.

📋 Repositorios

La plataforma está dividida en cuatro repositorios bajo la organización Rial-Cenia en GitHub:

Repositorio	Descripción
`rial-backend`	API NestJS (Node 22, Yarn 4)
`rial-frontend`	App Next.js 16 con Turbopack (React 19, Tailwind 4)
`rial-workers`	Cloud Functions de procesamiento (admin-metrics, faceswap-recognition, images-download)
`rial-platform-docker`	Docker Compose que orquesta todo el stack local

🔑 Permisos y Accesos Necesarios

Antes de comenzar, solicita acceso al administrador del equipo para:

GitHub — organización Rial-Cenia (acceso a los cuatro repos)
Google Cloud Platform (GCP) — proyecto interfaz-464700; necesitas el archivo google_credentials.json de una service account con permisos de Storage y Cloud Tasks
Secrets Manager — secrets.rial-ai.com para obtener los valores de .env
Supabase (opcional) — para consultar la base de datos de producción
Squarespace (opcional) — gestor del dominio

🛠️ Instalación de Herramientas

1. 🐳 Docker Desktop

Todo el stack local corre en Docker. Es el único requisito imprescindible.

Descarga desde docker.com/products/docker-desktop
Instala y abre Docker Desktop
Verifica:


docker --version       # Docker version 26.x o superior
docker compose version # Docker Compose version v2.x

2. 🔧 Git


# macOS (viene preinstalado, o con Homebrew)
brew install git
 
# Configuración inicial
git config --global user.name "Tu Nombre"
git config --global user.email "tu@email.com"

3. 📦 Node.js + Yarn (para trabajo fuera de Docker)

Opcional si solo quieres levantar el stack. Necesario para correr migraciones Prisma manualmente, instalar dependencias del frontend fuera del contenedor, etc.

Instala Node.js v22 LTS desde nodejs.org
Instala Yarn 4:


corepack enable
corepack prepare yarn@4.14.1 --activate

4. 🐘 PostgreSQL Client (para restaurar la DB)

Solo necesario si vas a restaurar un dump de producción.


# macOS
brew install postgresql@17
echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

5. 💻 Editor de Código

Recomendamos editores con IA integrada:

Cursor: cursor.sh — VS Code con IA nativa
VS Code: code.visualstudio.com con GitHub Copilot

Extensiones recomendadas para VS Code/Cursor: Prettier, ESLint, Prisma, Tailwind CSS IntelliSense, Docker.

📥 Clonar los Repositorios

Crea un directorio raíz y clona los cuatro repos al mismo nivel. La ruta relativa entre ellos importa porque Docker Compose los referencia así.


mkdir ~/rial && cd ~/rial
 
git clone https://github.com/Rial-Cenia/rial-backend.git
git clone https://github.com/Rial-Cenia/rial-frontend.git
git clone https://github.com/Rial-Cenia/rial-workers.git
git clone https://github.com/Rial-Cenia/rial-platform-docker.git docker

La estructura debe quedar así:


~/rial/
├── docker/               ← rial-platform-docker
├── rial-backend/
├── rial-frontend/
└── rial-workers/

🔐 Configuración de Secretos

1. Variables de entorno del backend

Crea rial-backend/.env con las variables obtenidas desde secrets.rial-ai.com . Este archivo es leído directamente por el contenedor Docker del backend.

Las variables clave son:


# Base de datos (Supabase local — ya definida en docker/.env, no cambiar para dev)
DATABASE_URL=...
DATABASE_URL_DIRECT=...

# Auth
JWT_SECRET=...

# Supabase
SUPABASE_URL=...
SUPABASE_SERVICE_ROLE_KEY=...

# GCP
GOOGLE_PROJECT_ID=...
GOOGLE_BUCKET_NAME=...
GCP_REGION=...
GOOGLE_APPLICATION_CREDENTIALS=/credentials/google_credentials.json

# Cloud Tasks (queues)
GOOGLE_CLOUD_TASKS_DOWNLOAD_QUEUE_NAME=...
GOOGLE_CLOUD_TASKS_ADMIN_METRICS_QUEUE_NAME=...
GOOGLE_CLOUD_TASKS_FACESWAP_RECOGNITION_QUEUE_NAME=...
GOOGLE_CLOUD_TASKS_OIDC_SERVICE_ACCOUNT_EMAIL=...

# Workers (URLs internas Docker — ya definidas en docker/.env)
DOWNLOAD_WORKER_URL=http://images-download-worker:8080
ADMIN_METRICS_WORKER_URL=http://admin-metrics-worker:8080
FACESWAP_RECOGNITION_WORKER_URL=http://faceswap-recognition-worker:8080

2. Variables de entorno del worker faceswap-recognition

Crea rial-workers/faceswap-recognition/.env (también disponible en secrets.rial-ai.com).

3. Credenciales de Google Cloud

Coloca el archivo google_credentials.json (service account GCP) en la raíz del monorepo (~/rial/google_credentials.json). Docker lo monta como volumen read-only dentro de los contenedores que lo necesitan.

4. `docker/.env` — ya viene configurado

El archivo docker/.env ya viene incluido en el repositorio con los valores por defecto para desarrollo local (JWT local, claves anon de Supabase demo, puertos, etc.). No necesitas editarlo salvo que quieras cambiar puertos.

▶️ Levantar el Stack Local


cd ~/rial/docker
docker compose up --build

Este comando construye las imágenes y levanta todos los servicios. La primera vez tarda varios minutos.

Para correr en segundo plano:


docker compose up --build -d

Para ver los logs de un servicio específico:


docker compose logs -f backend
docker compose logs -f frontend

Servicios y puertos

Servicio	URL local	Descripción
Frontend	localhost:3000	App Next.js
Backend (API)	localhost:4000	API NestJS
Supabase Studio	localhost:54323	UI de la base de datos
Supabase API (Kong)	localhost:54321	Gateway REST/Auth de Supabase
Supabase DB	`localhost:54322`	PostgreSQL directo (psql)
Cloud Tasks Emulator	`localhost:8123`	Emulador de Google Cloud Tasks
Swagger / API Docs	localhost:4000/api	Documentación de la API

Los workers (admin-metrics, faceswap-recognition, images-download) corren internamente en la red Docker en el puerto 8080 y son invocados por el backend via Cloud Tasks.

🗄️ Base de Datos

Opción A — Base de datos vacía (default)

Al iniciar, el backend ejecuta automáticamente prisma migrate deploy, que aplica todas las migraciones pendientes sobre la base de datos local. No necesitas hacer nada más.

Opción B — Restaurar dump de producción

Si necesitas datos reales de producción para desarrollar:


# Desde la raíz del monorepo (~/rial), con supabase-db ya corriendo
./docker/db/restore-supabase-dump.sh docker/db/supabase-17-07.dump

El script:

Restaura el dump con pg_restore
Sincroniza las contraseñas de roles Supabase al valor local (postgres)
Aplica los SQLs de compatibilidad (GoTrue, Realtime, Prisma ownership)
Corre prisma migrate deploy para aplicar migraciones más nuevas que el dump

Nota: Necesitas pg_restore instalado localmente (ver sección de herramientas). El dump más reciente está en docker/db/.

Para forzar un schema limpio antes de restaurar:


cd ~/rial/docker
docker compose down
docker volume rm docker_supabase_db_data   # o el nombre que muestre: docker volume ls
docker compose up -d supabase-db
# Esperar ~10s a que esté healthy, luego:
./docker/db/restore-supabase-dump.sh docker/db/supabase-17-07.dump

Acceder a la base de datos

Supabase Studio (UI): localhost:54323
Prisma Studio:


cd ~/rial/rial-backend
yarn db:studio   # abre en http://localhost:5555

psql directo:


psql -h localhost -p 54322 -U postgres -d postgres

🔄 Comandos de Desarrollo Diarios

Stack completo


# Levantar todo
docker compose up -d
 
# Detener todo
docker compose down
 
# Reconstruir un servicio específico (ej. tras cambiar Dockerfile)
docker compose up --build backend
 
# Ver logs en tiempo real
docker compose logs -f backend
docker compose logs -f frontend

Backend (NestJS)

El contenedor Docker hace hot-reload automático con nest start --watch. Si necesitas correr comandos manualmente:


cd ~/rial/rial-backend
 
yarn install           # instalar dependencias
yarn start:dev         # iniciar sin Docker (requiere .env local apuntando a DB)
yarn test              # unit tests
yarn test:e2e          # tests end-to-end
yarn lint              # ESLint
yarn db:migrate        # crear/aplicar nueva migración Prisma
yarn db:deploy         # aplicar migraciones pendientes (usado en producción)
yarn db:generate       # regenerar el cliente Prisma
yarn db:studio         # abrir Prisma Studio
yarn db:seed           # correr el seed de la base de datos

Frontend (Next.js)

El contenedor Docker corre next dev --turbopack con hot-reload. Si necesitas correr fuera de Docker:


cd ~/rial/rial-frontend
 
yarn install           # instalar dependencias
yarn dev               # iniciar con Turbopack en localhost:3000
yarn build             # build de producción
yarn lint              # ESLint
yarn test              # Playwright e2e
yarn storybook         # Storybook en localhost:6006

Workers

Los workers corren en Docker y se reconstruyen automáticamente. Para inspeccionarlos:


docker compose logs -f images-download-worker
docker compose logs -f admin-metrics-worker
docker compose logs -f faceswap-recognition-worker

🐛 Solución de Problemas Comunes

El contenedor backend no levanta / error de DB

Verifica que supabase-db esté healthy: docker compose ps
Revisa los logs: docker compose logs backend
Si hay error de migraciones Prisma con P3005 (schema no vacío sin historial), fuerza db push:


# En docker/.env (temporalmente)
PRISMA_DOCKER_DB_PUSH_ONLY=1
docker compose up --build backend

Error: “Puerto ya en uso”


lsof -i :3000   # o el puerto que corresponda
kill -9 <PID>

Rebuilding desde cero


cd ~/rial/docker
docker compose down
docker volume rm docker_supabase_db_data docker_backend_yarn_cache
docker compose up --build

Error de módulo no encontrado (node_modules desincronizado)


# El volumen anónimo de node_modules puede quedar desactualizado
docker compose down
docker volume prune    # elimina volúmenes no usados (confirmar con 'y')
docker compose up --build

GoTrue (auth) no conecta después de restaurar dump


docker compose restart supabase-auth

🎯 Próximos Pasos

Una vez que tengas todo corriendo:

📖 Lee el Diccionario Técnico — familiarízate con los términos
🔍 Explora el Esquema de Base de Datos — entiende la estructura de datos
🌊 Aprende los Flujos — cómo funciona la creación de proyectos, subida de imágenes, etc.
⚙️ Revisa los Workers — cómo funcionan las Cloud Functions de procesamiento

🔗 Recursos

Secretos y variables de entorno: secrets.rial-ai.com
Analytics y dashboards: analytics.rial-ai.com
Supabase Studio (local): localhost:54323
API Swagger (local): localhost:4000/api