Despliegue con Dokploy

Esta guía cubre el despliegue completo de Vitality Gym usando Dokploy, incluyendo todos los servicios: Backend (API), Frontend (App), Base de Datos (PostgreSQL), Cache (Redis), y Email (BillionMail).

Requisitos Previos

• VPS con mínimo 2GB RAM, 2 CPU, 40GB SSD
• Dominio configurado (ej: vitality-gym.com)
• Dokploy instalado en el servidor

Instalación de Dokploy

curl -sSL https://dokploy.com/install.sh | sh

Accede al panel en http://tu-ip:3000 y configura tu cuenta admin.

Puertos Requeridos

Los siguientes puertos son utilizados por los servicios:

Puerto	Servicio	Descripción
3000	API	Backend Hono/Bun
4321	App	Frontend Astro
5432	PostgreSQL	Base de datos
6379	Redis	Cache
25, 587, 993	BillionMail	SMTP/IMAP

Verificar Puertos Disponibles

# Verificar si un puerto está en uso
ss -tulpn | grep :3000

# O con netstat
netstat -tulpn | grep :5432

# Ver todos los puertos en uso
ss -tulpn | grep LISTEN

Puertos Ocupados

Si un puerto está ocupado, puedes cambiarlo en Dokploy:

1. Ir al servicio → Ports
2. Cambiar el Host Port (el puerto del contenedor puede mantenerse igual)
3. Actualizar las variables de entorno que referencien ese puerto

Por ejemplo, si el puerto 5432 está ocupado por otra instancia de PostgreSQL:

• Cambia el Host Port a 5433
• Actualiza DATABASE_URL a usar ...@database:5433/...

---

Arquitectura de Servicios

graph TB
    subgraph Dokploy
        subgraph Project["Proyecto: vitality-gym"]
            DB[(PostgreSQL 17)]
            Redis[(Redis 7)]
            API[API - Hono/Bun]
            App[Frontend - Astro]
            Mail[BillionMail]
        end
    end

    Internet --> Traefik
    Traefik --> App
    Traefik --> API
    Traefik --> Mail
    API --> DB
    API --> Redis
    API --> Mail

---

Paso 1: Crear Proyecto

1. En Dokploy, ir a Projects → Create Project
2. Nombre: vitality-gym
3. Descripción: Sistema de gestión de gimnasio

---

Paso 2: Base de Datos (PostgreSQL)

1. Dentro del proyecto, click en Create Service → Database → PostgreSQL

2. Configurar:

   • Name: database
   • Image: postgres:17
   • Database Name: vitality_db
   • Username: vitality_user
   • Password: (genera una contraseña segura)

3. En Advanced → Volumes, agregar:

   /var/lib/postgresql/data → vitality-db-data

4. En Environment, agregar:

   TZ=America/Bogota

5. Click Deploy

Connection String

Dokploy genera automáticamente la URL de conexión. La encontrarás en el servicio como:

postgresql://vitality_user:PASSWORD@database:5432/vitality_db

---

Paso 3: Cache (Redis)

1. Create Service → Database → Redis

2. Configurar:

   • Name: redis
   • Image: redis:7

3. En Advanced → Volumes:

   /data → vitality-redis-data

4. Click Deploy

Note

La URL será: redis://redis:6379

---

Paso 4: Email (BillionMail)

1. Create Service → Compose
2. Nombre: billionmail
3. Pegar la configuración de BillionMail según su documentación
4. Configurar los dominios y DNS records

Una vez configurado, tendrás credenciales SMTP:

SMTP_HOST=mail.vitality-gym.com
SMTP_PORT=587
SMTP_USER=noreply@vitality-gym.com
SMTP_PASS=tu_password_smtp

---

Paso 5: Backend (API)

1. Create Service → Application

2. Configurar:

   • Name: api
   • Source: GitHub
   • Repository: tu repositorio
   • Branch: main
   • Build Type: Dockerfile
   • Dockerfile Path: packages/api/Dockerfile

3. En Domains, agregar:

   • Domain: api.vitality-gym.com (o testing.api.vitality-gym.com para staging)
   • HTTPS: Enabled (Let’s Encrypt)

4. En Ports:

   • Container Port: 3000
   • Scheme: https

Variables de Entorno (API)

En la pestaña Environment, configura:

Requeridas

# Core
NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://vitality_user:PASSWORD@database:5432/vitality_db
AUTH_SECRET=genera_un_secret_seguro_de_32_chars

# Redis
REDIS_URL=redis://redis:6379

# URLs (usar testing.* para staging)
FRONTEND_URL=https://app.vitality-gym.com  # o https://testing.app.vitality-gym.com
BACKEND_URL=https://api.vitality-gym.com   # o https://testing.api.vitality-gym.com
CORS_ORIGINS=https://app.vitality-gym.com,https://vitality-gym.com,https://testing.app.vitality-gym.com

# Email (BillionMail)
SMTP_HOST=mail.vitality-gym.com
SMTP_PORT=587
SMTP_USER=noreply@vitality-gym.com
SMTP_PASS=tu_password_smtp

# Uploads
UPLOAD_DIR=/app/packages/api/uploads

OAuth (Opcional)

# Google OAuth
GOOGLE_CLIENT_ID=tu_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=tu_client_secret

Push Notifications

# VAPID Keys (generar con: npx web-push generate-vapid-keys)
VAPID_PUBLIC_KEY=BLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VAPID_PRIVATE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VAPID_SUBJECT=mailto:admin@vitality-gym.com

Wompi (Pagos)

# Wompi Colombia
WOMPI_SANDBOX=false
WOMPI_PUBLIC_KEY=pub_prod_xxxxxxxxxxxx
WOMPI_PRIVATE_KEY=prv_prod_xxxxxxxxxxxx
WOMPI_EVENTS_KEY=prod_events_xxxxxxxxxxxx
WOMPI_INTEGRITY_KEY=prod_integrity_xxxxxxxxxxxx

Volúmenes (Persistencia de Uploads)

En Advanced → Volumes:

/app/packages/api/uploads → vitality-uploads

5. Click Deploy

---

Paso 6: Frontend (App)

1. Create Service → Application

2. Configurar:

   • Name: app
   • Source: GitHub (mismo repositorio)
   • Branch: main
   • Build Type: Dockerfile
   • Dockerfile Path: packages/app/Dockerfile

3. En Build Arguments:

   BACKEND_URL=https://api.vitality-gym.com  # o https://testing.api.vitality-gym.com

4. En Domains, agregar:

   • Domain: app.vitality-gym.com (o testing.app.vitality-gym.com para staging)
   • HTTPS: Enabled

5. En Ports:

   • Container Port: 4321
   • Scheme: https

6. Click Deploy

---

Paso 7: Migraciones y Seed de Base de Datos

Ejecutar Migraciones

Después de que el API esté desplegado, accede a la terminal del contenedor:

# En Dokploy: Service → api → Terminal
cd /app
bunx prisma migrate deploy --schema=./packages/database/prisma/schema.prisma

O desde tu máquina local con la DATABASE_URL de producción:

DATABASE_URL="postgresql://user:pass@host:5432/db" bunx prisma migrate deploy

Migraciones Posteriores (Post-Despliegue)

Cuando realices cambios en el schema.prisma después de que la aplicación ya esté en producción, sigue estos pasos para actualizar la base de datos sin perder datos:

1. Generar la migración localmente:

   # En la raíz del proyecto
   bun run db:migrate --name nombre_de_tu_migración

   Esto creará una nueva carpeta en packages/database/prisma/migrations.

2. Subir los cambios al repositorio: Haz commit y push de los nuevos archivos de migración.

3. Desplegar la nueva versión del API: Dokploy detectará el cambio y reconstruirá el contenedor del API.

4. Aplicar la migración en producción: Una vez que el nuevo contenedor esté corriendo, usa la terminal de Dokploy en el servicio api:

   bunx prisma migrate deploy --schema=./packages/database/prisma/schema.prisma

Prisma Migrate Deploy

El comando migrate deploy es seguro para producción ya que solo aplica migraciones pendientes sin intentar resetear la base de datos ni generar advertencias interactivas que requieran confirmación manual.

Seed de Datos Iniciales

# En el contenedor de API
bun run packages/database/seed.ts

Seed en Producción

Ejecuta el seed solo una vez en el setup inicial. Verifica que el script de seed sea idempotente o tenga verificaciones para no duplicar datos.

---

Paso 8: Configuración DNS

Configura los siguientes registros DNS en tu proveedor:

Tipo	Nombre	Valor
A	@	IP del servidor
A	api	IP del servidor
A	app	IP del servidor
A	docs	IP del servidor
A	testing.api	IP del servidor
A	testing.app	IP del servidor
CNAME	www	vitality-gym.com

Para BillionMail, agrega también los registros MX, SPF, DKIM y DMARC según su documentación.

---

Paso 9: Verificación Post-Deploy

Checklist

• API responde en https://api.vitality-gym.com/health (o testing.api.*)
• Frontend carga en https://app.vitality-gym.com (o testing.app.*)
• Login con email funciona
• Login con Google funciona (si está configurado)
• Envío de emails funciona (reset password)
• Uploads de archivos funcionan
• Pagos con Wompi funcionan (usar sandbox primero)
• Push notifications funcionan

Comandos Útiles

Dokploy CLI

# Ver logs del API
dokploy logs api --follow

# Reiniciar servicio
dokploy restart api

# Acceder a terminal
dokploy exec api sh

Docker CLI

# Ver logs del API
docker logs vitality-api -f

# Reiniciar servicio
docker restart vitality-api

# Acceder a terminal
docker exec -it vitality-api sh

---

Configuración de Webhooks

Wompi Webhook

En el panel de Wompi, configura:

• Producción: https://api.vitality-gym.com/api/v1/payments/webhook
• Staging: https://testing.api.vitality-gym.com/api/v1/payments/webhook
• Evento: transaction.updated

---

Troubleshooting

Database Connection

# Verificar conexión desde API
bun -e "console.log(await fetch('http://localhost:3000/health').then(r=>r.json()))"

# Verificar PostgreSQL
psql postgresql://user:pass@database:5432/vitality_db -c "SELECT 1"

Redis

# Test de conexión
redis-cli -h redis ping
# Debe responder: PONG

Migrations

# Ver estado de migraciones
bunx prisma migrate status

# Reset (¡CUIDADO EN PRODUCCIÓN!)
bunx prisma migrate reset --force

---

Backups

Base de Datos

Docker CLI

# Backup manual
docker exec -t vitality-database pg_dumpall -c -U vitality_user > backup_$(date +%Y%m%d).sql

# Restaurar
cat backup.sql | docker exec -i vitality-database psql -U vitality_user

docker-compose

# Si usas docker-compose, el nombre del contenedor puede variar
docker-compose exec database pg_dumpall -c -U vitality_user > backup_$(date +%Y%m%d).sql

# Restaurar
cat backup.sql | docker-compose exec -T database psql -U vitality_user

Configurar Backup Automático en Dokploy

1. Ir a Settings → Backups
2. Configurar destino (S3, local, etc.)
3. Programar backups diarios

---

Escalamiento

Para alto tráfico, considera:

• Horizontal Scaling: Múltiples instancias del API con load balancer
• PgBouncer: Connection pooling para PostgreSQL
• Redis Cluster: Para alta disponibilidad del cache
• CDN: CloudFlare o similar para assets estáticos

---

Resumen de Variables de Entorno

Variables Requeridas

Variable	Servicio	Descripción
DATABASE_URL	API	Conexión PostgreSQL
AUTH_SECRET	API	Secret para JWT (32+ chars)
REDIS_URL	API	Conexión Redis
SMTP_*	API	Credenciales email
FRONTEND_URL	API	URL del frontend
BACKEND_URL	API, App	URL del backend
CORS_ORIGINS	API	Orígenes permitidos
GOOGLE_CLIENT_*	API	OAuth de Google
UPLOAD_DIR	API	Directorio de uploads
WOMPI_*	API	Pasarela de pagos
VAPID_*	API	Push notifications