Manual de Despliegue · DOC-INS-01

Instalación y Configuración

Cómo desplegar Plazi desde cero o reproducir el entorno completo

Documento

DOC-INS-01

Versión

1.0 · jun 2026

Audiencia

DevOps · Engineering

Tiempo estimado

45-60 min

1 · Prerrequisitos

Lo que necesitás antes de empezar

Software local

Herramienta	Versión mínima	Verificar con
Node.js	22.0.0 LTS (Vercel default)	`node --version`
pnpm	9.0+	`pnpm --version`
Git	2.40+	`git --version`
PowerShell o Bash	5.1+ / 5.0+	—

Cuentas de servicios externos

Servicio	Para qué	Plan
GitHub	Repositorio + webhooks de deploy	Free
Vercel	Hosting web + CI/CD + dominios	Pro recomendado
Supabase	Postgres + Auth + Storage	Pro (backups diarios)
Resend	Emails transaccionales	Free (10k emails/mes)
Wompi (Bancolombia)	Pagos: Nequi, PSE, tarjeta	Merchant CO
Expo (EAS)	Build APK/IPA del mobile	Free / Production
Porkbun	Registro del dominio `plazi.co`	—

Acceso del repositorio: el repo github.com/SebasInvent/plazi es privado. Sebastián M. (CTO) gestiona los accesos vía gh auth.

DOC-INS-01 · Página 1

2 · Instalación local

Levantar el entorno de desarrollo en 5 pasos

1Clonar el repositorio

git clone https://github.com/SebasInvent/plazi.git
cd plazi

2Instalar dependencias del monorepo

pnpm install

Instala todas las deps de apps/web, apps/mobile, apps/api y los 4 packages internos en un solo paso.

3Copiar archivos de entorno

cp apps/web/.env.example apps/web/.env.local
cp apps/mobile/.env.example apps/mobile/.env.local

Llená cada variable según la siguiente sección.

4Aplicar migraciones SQL

Abrí Supabase Studio → SQL Editor y corré, en orden, todos los archivos de supabase/migrations/:

20260516120000_init.sql
20260516120100_seed_catalog.sql
20260520010000_seed_demo_products.sql
20260520195000_order_status_enum_values.sql
20260520200000_reviews_coupons_cancellations.sql
20260606130000_wishlists_notifications.sql

5Arrancar el dev server

# Sitio web (puerto 3000)
pnpm --filter @plazi/web dev

# Mobile (Expo Dev Server)
pnpm --filter @plazi/mobile dev

DOC-INS-01 · Página 2

3 · Variables de entorno

Configuración de secretos y parámetros

3.1 · Supabase (web + mobile)

# apps/web/.env.local
NEXT_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...   # pública por diseño · RLS protege
SUPABASE_SERVICE_ROLE_KEY=eyJ...        # SECRETA · solo server-side

# apps/mobile/.env.local
EXPO_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=eyJ...
EXPO_PUBLIC_API_BASE_URL=https://plazi.co
EXPO_PUBLIC_SITE_URL=https://plazi.co

3.2 · Wompi (pagos)

# apps/web/.env.local
WOMPI_PUBLIC_KEY=pub_test_xxx       # sandbox o producción
WOMPI_PRIVATE_KEY=prv_test_xxx
WOMPI_EVENTS_SECRET=xxx             # para validar webhooks
NEXT_PUBLIC_WOMPI_PUBLIC_KEY=pub_test_xxx

3.3 · Resend (emails)

RESEND_API_KEY=re_xxx
RESEND_FROM=Plazi <hola@plazi.co>

3.4 · Push notifications (Expo)

# apps/web/.env.local
BEEGO_ADMIN_SECRET=xxx               # auth header en /api/push/notify

# apps/mobile/.env.local
EXPO_PUBLIC_EAS_PROJECT_ID=00000000-0000-0000-0000-000000000000
# Lo genera `eas init`. Pegarlo también en app.json:expo.extra.eas.projectId

3.5 · Soporte

NEXT_PUBLIC_SUPPORT_WHATSAPP=573001234567   # número real de soporte

⚠ NUNCA commitear archivos .env.local. Ya están en .gitignore. Para producción, cargar las variables en Vercel Dashboard → Settings → Environment Variables.

DOC-INS-01 · Página 3

4 · Despliegue a producción

Vercel + GitHub auto-deploy

Opción A · Auto-deploy desde GitHub (recomendado)

Conectar el repo SebasInvent/plazi en vercel.com → Add New → Project
Root Directory: dejar en blanco (Vercel detecta el monorepo)
Framework Preset: Next.js
Build Command: cd ../.. && pnpm turbo build --filter=@plazi/web
Output Directory: apps/web/.next
Cargar todas las env vars en Settings → Environment Variables
Cada git push origin master dispara un deploy automático

Opción B · Deploy manual con Vercel CLI

npm i -g vercel
cd plazi
vercel --prod

Configuración recomendada de Vercel

Node version: 24 LTS (default actual)
Function timeout: 300s (default Pro plan)
Fluid Compute: activado (default)
Edge regions: auto (lat-am preferred)

Conectar el dominio plazi.co

En Vercel: Settings → Domains → Add · escribí plazi.co
Copiar los registros DNS que entrega Vercel
En Porkbun (panel de DNS de plazi.co): pegar A + CNAME
Esperar propagación (~10 min)
Vercel valida y emite el certificado SSL automáticamente

Verificación post-deploy

# Health check
curl https://plazi.co/

# Endpoint público (debe devolver JSON con productos)
curl https://plazi.co/api/products?limit=5

# Verificación de build status
gh run list --limit 1 --repo SebasInvent/plazi

DOC-INS-01 · Página 4

5 · Build del mobile (EAS)

Generar APK Android para los comerciantes piloto

1Instalar EAS CLI global

npm install -g eas-cli

2Login en EAS

cd apps/mobile
eas login   # usa tu cuenta expo.dev

3Inicializar el proyecto

eas init   # genera projectId real y lo escribe en app.json

4Cargar credenciales Supabase a la nube de EAS

eas env:create --environment preview --name EXPO_PUBLIC_SUPABASE_URL --type string --visibility plaintext
eas env:create --environment preview --name EXPO_PUBLIC_SUPABASE_ANON_KEY --type string --visibility plaintext

5Generar el APK Beta (Android)

eas build --platform android --profile preview

Sube el código a la nube de Expo, compila (~10-15 min) y entrega un link descargable al APK. Ese link se distribuye por WhatsApp a los 5-10 comerciantes piloto del Centro Comercial Lo Nuestro.

OTA Updates (sin re-build)

Para parches de JS/JSX/TS sin tocar capa nativa:

eas update --branch preview --message "fix: corregir estado vacío pedidos"

Los usuarios reciben el update al abrir la app la próxima vez. No hay que reinstalar.

Troubleshooting frecuente

Problema	Solución
`eas build` falla por assets	Verificar que `apps/mobile/assets/icon.png`, `splash.png` y `adaptive-icon.png` existen
Push no llegan en Expo Go	Expo Go solo soporta push limitado. Usar APK preview
Cámara devuelve "permission-denied"	Settings del device → Plazi → Permitir cámara
Build pide keystore Android	Aceptar opción default "Generate new keystore"
Migración SQL falla por dependencias	Aplicar en orden cronológico estricto

Contacto para soporte técnico

📧 Soporte técnico: sebastian@inventagency.co
📚 Documentación API: /equipo/api-guide.html
🧪 Suite de testing: /equipo/plazi-tests-package.zip
📦 Repositorio: github.com/SebasInvent/plazi

DOC-INS-01 · Página 5 (final)