Saltar al contenido principal

Guía de Despliegue - Fyso

Esta guía explica cómo desplegar diferentes instancias (MVPs) del proyecto Fyso en el servidor de producción.

Arquitectura de Despliegue​

Cada MVP se despliega en una carpeta independiente en el home del usuario fyso y corre como un conjunto de procesos PM2 separados.

ComponenteDescripción
NginxActúa como Reverse Proxy, manejando SSL (Certbot) y redirigiendo el tráfico al puerto del MVP correspondiente.
PM2Gestor de procesos para el API (Bun) y la Web (Next.js).
BunRuntime utilizado para la ejecución y construcción.

Script de Despliegue Genérico​

Se ha implementado un script centralizado deploy-generic.sh que automatiza todo el proceso.

Uso del Script Genérico​

El script acepta 4 parámetros:

  1. MVP_NAME: Nombre de la instancia (ej: mvp2, mvp3).
  2. BRANCH: Rama de Git a desplegar.
  3. API_PORT: Puerto donde correrá el API.
  4. WEB_PORT: Puerto donde correrá la Web (Next.js).
./deploy-generic.sh "nombre" "rama" "puerto_api" "puerto_web"

Ejemplo: Crear un nuevo MVP (MVP3)​

  1. Crea un archivo deploy-mvp3-git.sh: 
    #!/bin/bash
    ./deploy-generic.sh "mvp3" "feat/mvp3-branch" "3005" "3004"
  2. Dale permisos de ejecución: chmod +x deploy-mvp3-git.sh
  3. Ejecútalo: ./deploy-mvp3-git.sh

Configuración de Nginx​

Cuando subas un nuevo MVP (ej. MVP3), debes configurar Nginx en el servidor:

  1. SSH al servidor: ssh fyso@212.47.245.39
  2. Crear configuración en /etc/nginx/sites-available/mvp3.fyso.dev: 
    server {
        server_name mvp3.fyso.dev;
        location / {
            proxy_pass http://localhost:3004; # Puerto WEB del MVP
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
        }
        listen 80;
    }
  3. Habilitar y pedir certificado SSL: 
    sudo ln -s /etc/nginx/sites-available/mvp3.fyso.dev /etc/nginx/sites-enabled/
    sudo nginx -t
    sudo systemctl reload nginx
    sudo certbot --nginx -d mvp3.fyso.dev

Variables de Entorno (.env)​

El script genera automáticamente el archivo .env básico. Nota Importante: El script preserva la OPENAI_API_KEY si ya existe en el servidor. Si es un despliegue nuevo, deberás editar el .env manualmente la primera vez o actualizar el script base.

Variables MCP (MVP-5)​

Para el MCP público (ej: mvp5.fyso.dev) se deben configurar estas variables:

  • MCP_SERVER_URL: URL pública del MCP (ej: https://mvp5.fyso.dev/mcp). Se usa para generar la configuración de Claude Desktop.
  • MCP_SERVER_PORT: Puerto del MCP server (ej: 3006).
  • MCP_SERVER_PATH: Path del MCP server (default /mcp).

El MCP server corre como proceso separado (Bun) y necesita:

  • FYSO_API_URL: URL del API (ej: http://localhost:3005/api).
  • FYSO_API_KEY: No se configura a nivel servidor para multi-tenant; el cliente la envía via header X-API-Key.

Troubleshooting MCP (MVP-6)​

Sintomas vistos (30 Jan 2026):

  • 406 Not Acceptable: Client must accept both application/json and text/event-stream
  • Streamable HTTP error: Bad Request: No valid session
  • Tool calls fallan con: API response was not JSON (404) ... nginx

Resolucion aplicada:

  1. Aceptar headers correctos en el server MCP
    • El cliente HTTP debe enviar Accept: application/json, text/event-stream.
    • Se agrego un merge de Accept en packages/mcp-server/src/http-server.ts para evitar el 406.
  2. Usar el endpoint correcto
    • HTTP: https://mvp6.fyso.dev/mcp
    • SSE: https://mvp6.fyso.dev/mcp/sse
  3. Autenticacion
    • Preferir Authorization: Bearer <API_KEY> (tambien se acepta X-API-Key).
  4. FYSO_API_URL mal formado
    • Se detecto FYSO_API_URL=http://localhost:\3012/api (backslash) en .env.
    • Corregir a http://localhost:3012/api para evitar 404 HTML de nginx en tool calls.

Comandos recomendados (Claude Code CLI):

claude mcp add --transport http mvp6 https://mvp6.fyso.dev/mcp \
  --header "Authorization: Bearer <TU_API_KEY>"

Lecciones Aprendidas (MVP-4 Deployment)​

Durante el despliegue del MVP-4 se identificaron puntos críticos que deben considerarse para futuros lanzamientos:

  1. Dependencia de Runtime (Bun vs Node):

    • Problema: Comandos como turbo intentan invocar node por defecto. Si el servidor solo tiene bun, estos comandos fallarán.
    • Solución: Ejecutar los scripts de base de datos directamente con Bun (bun run src/migrate.ts) en lugar de usar el wrapper de Turbo o scripts de npm que dependan de Node.

  2. Migraciones y Seed:

    • Problema: Al introducir cambios estructurales (como el sistema multi-tenant), el despliegue de código no es suficiente; la base de datos debe actualizarse.
    • Solución: Asegurar que el script de despliegue ejecute db:migrate y db:seed. Es recomendable usar rutas absolutas para el binario de Bun ($HOME/.bun/bin/bun).

  3. Configuración de Nginx (Automatización):

    • Problema: El nuevo subdominio no funciona hasta que Nginx lo reconoce.
    • Solución: Cada nuevo MVP requiere su archivo en /etc/nginx/sites-available/.
    • Tip de Bash: Al crear archivos de configuración vía SSH con cat << "EOF", usa comillas en el EOF para evitar que las variables de Nginx (como $http_upgrade) se expandan localmente en tu terminal antes de enviarse al servidor.

  4. Verificación de Rama:

    • Problema: Desplegar la rama incorrecta (ej. main en lugar de la rama de la fase).
    • Solución: Verificar siempre git branch --show-current antes de ejecutar el script de despliegue.

Checklist para un Nuevo MVP​

  • Crear script deploy-mvpX.sh con la rama y puertos correctos.
  • Verificar que los puertos API y WEB no colisionen con otros MVPs (pm2 list).
  • Definir puerto MCP si aplica (MVP-5+) y agregarlo a PM2.
  • Configurar MCP_SERVER_URL en .env para el subdominio correcto.
  • Ejecutar migraciones de DB en el servidor.
  • Crear y habilitar sitio en Nginx.
  • Ejecutar certbot para el nuevo subdominio.
  • Verificar logs de PM2 (pm2 logs nombre-app).
Creado con Fyso