Visión general

El autoalojamiento empieza por el stack de la aplicación. La facturación, el almacenamiento, el correo y la analítica son decisiones de infraestructura adicionales, una vez ese stack está sano.

Pila mínima desplegable

Ahora mismo el repositorio no ofrece un despliegue de producción con un solo comando. Antes de seguir las guías de servicios opcionales, planifica y opera:

• PostgreSQL 17 con la extensión pgvector, migraciones, copias de seguridad y pruebas de restauración
• Redis para las colas, la caché y la coordinación en tiempo real
• el servicio de API, la aplicación web y los workers en segundo plano de la misma versión
• las URLs públicas de web, API y WebSocket, TLS, los orígenes permitidos y los secretos y URLs de Better Auth
• entrega de trabajos compatible con QStash/Workflow y sus claves de firma
• una clave de proveedor de IA y una política de modelos para las funciones de IA y de embeddings que actives: o una clave de Vercel AI Gateway (AI_GATEWAY_API_KEY, la opción por defecto) o una de OpenRouter (OPENROUTER_API_KEY), seleccionadas con AI_PROVIDER
• almacenamiento y rotación de secretos, registros estructurados, comprobaciones de salud, alertas y vuelta atrás

El docker-compose.yml local es una base de desarrollo para Postgres, Redis y GeoIP. No es una topología de producción. Ejecuta las migraciones antes de servir una versión nueva y mantén alineados en la misma versión la API, la web, los workers, el esquema y lo que espera el SDK publicado.

Cuando ese núcleo esté funcionando, resuelve estas cuatro responsabilidades:

Fluxo espera:

• una decisión clara sobre el modo de facturación: dejar Polar activado o desactivar la facturación y funcionar con permisos autoalojados ilimitados
• almacenamiento de objetos para las subidas y la lectura pública de archivos
• infraestructura de correo transaccional capaz de enviar correo, recibir respuestas e informar de los eventos de ciclo de vida
• infraestructura de analítica para las métricas de la bandeja y la presencia en vivo, o la decisión explícita de desactivar esas funciones de analítica gestionada

Recomendamos el camino de AWS para la instalación autoalojada oficial porque el repositorio ya trae módulos de Terraform para ella, pero la documentación de esta sección está organizada por funciones, no por proveedores:

• Facturación explica el interruptor POLAR_ENABLED, por qué Polar sigue activado por defecto y qué cambia al desactivar la facturación
• Almacenamiento cubre las subidas, la lectura pública de archivos y el camino de configuración con AWS S3
• Configuración del correo cubre el correo transaccional, las respuestas entrantes y cómo elegir entre Resend y SES
• Analítica cubre la analítica basada en Tinybird, las variables de entorno que activan Tinybird y DataFast, y qué pasa al desactivarla

Responsabilidad de la facturación

Fluxo tiene dos modos de facturación válidos al autoalojar:

• dejar Polar activado y conservar el comportamiento de suscripción y de medición de IA del producto alojado
• desactivar Polar y funcionar en un modo autoalojado donde se omiten los flujos de facturación, la medición de créditos y los límites de plan

Polar viene activado por defecto para que el repositorio se comporte como el producto gestionado, salvo que lo desactives explícitamente.

Usa la guía de facturación para decidir qué modo quieres y configurar POLAR_ENABLED.

Por qué recomendamos el camino de AWS

El repositorio ya trae módulos de Terraform para ambos servicios:

• infra/aws/s3-public-setup
• infra/aws/ses-email-setup

Eso importa porque el camino de autoalojamiento es concreto y no teórico. No empiezas de cero con un almacenamiento o un correo genéricos: sigues una infraestructura que ya encaja con lo que la aplicación espera en ejecución.

Responsabilidad del almacenamiento

Fluxo necesita un almacenamiento de objetos donde la API pueda generar URLs de subida prefirmadas y donde los archivos subidos se puedan volver a leer mediante URLs públicas estables.

En la práctica, eso significa:

• la API firma las subidas
• el navegador sube directamente al almacenamiento de objetos
• la aplicación guarda y muestra las URLs públicas resultantes
• los archivos subidos se pueden agrupar por organización, sitio web y entidad

Usa la guía de almacenamiento para configurarlo.

Responsabilidad del correo

Con el correo, Fluxo necesita algo más que el simple envío saliente. La aplicación también depende del enrutado de las respuestas y de los eventos de ciclo de vida.

En la práctica, eso significa:

• React Email genera el contenido del correo dentro de la aplicación
• el envío saliente se elige con EMAIL_TRANSPORT_PROVIDER
• las direcciones de respuesta apuntan a un dominio de entrada controlado por Fluxo
• las respuestas entrantes acaban volviendo a la API como cargas de webhook normalizadas
• los eventos de rebote, queja y fallo alimentan el estado de supresión

La buena noticia es que puedes elegir el transporte:

• resend está soportado y sigue siendo la opción por defecto
• ses está soportado y es el camino nativo de AWS para el autoalojamiento

Usa la guía de configuración del correo para elegir proveedor y configurar el camino completo de entrada y salida.

Responsabilidad de la analítica

Fluxo usa infraestructura de analítica para dos áreas del producto:

• la analítica de la bandeja de entrada
• la presencia de visitantes en vivo y el enriquecido de «última vez visto en la app»

Para el autoalojamiento tienes dos caminos válidos:

• dejar Tinybird activado y apuntar la aplicación a tu instalación de Tinybird
• desactivar Tinybird por completo y funcionar sin la interfaz de analítica que depende de él

La aplicación incluye además un script aparte de DataFast para nuestra analítica web alojada. Quien autoaloja puede desactivarlo de forma independiente.

Usa la guía de analítica para decidir cómo tratar Tinybird y DataFast en tu despliegue.

Cómo encajan las piezas

A grandes rasgos, un despliegue autoalojado tiene esta pinta:

1. Un navegador pide a la API una URL de subida prefirmada.
2. La API firma un PUT hacia S3 y devuelve la URL de subida junto con la URL pública.
3. El navegador sube el archivo directamente a S3 en lugar de hacerlo pasar por la API.
4. Fluxo envía el correo con plantillas de React Email y el proveedor que seleccione EMAIL_TRANSPORT_PROVIDER.
5. Las nuevas direcciones de respuesta apuntan al dominio de entrada del proveedor de correo activo.
6. Resend o SES devuelven a la API las respuestas entrantes y los eventos de ciclo de vida usando el puente propio de cada proveedor configurado en la aplicación.
7. La API convierte esos eventos en mensajes de la línea de tiempo, disparadores de notificación y registros de rebote o de queja.
8. La facturación con Polar sigue activada por defecto salvo que la desactives explícitamente con POLAR_ENABLED=false.
9. La analítica de la bandeja y la presencia en vivo basadas en Tinybird se activan mediante tu instalación de analítica o se desactivan explícitamente con variables de entorno.

Orden de configuración recomendado

Para un primer despliegue limpio:

1. Aprovisiona PostgreSQL con pgvector y Redis, configura los secretos y las URLs públicas, ejecuta las migraciones y arranca la API, la aplicación web y los workers.
2. Verifica la autenticación, la salud de la API, la conectividad de WebSocket, los trabajos en segundo plano y la copia y restauración antes de las integraciones opcionales.
3. Lee Facturación y decide si Polar sigue activado.
4. Configura el almacenamiento y verifica las subidas.
5. Configura el correo y prueba tanto el envío como las respuestas entrantes.
6. Configura los recursos de Tinybird del repositorio o desactiva explícitamente la analítica y DataFast.
7. Ensaya una actualización y una vuelta atrás en preproducción antes de recibir tráfico de producción.

Si haces un despliegue autoalojado desde cero y no piensas usar Resend en absoluto, puedes ir directamente a SES en cuanto confirmes que el DNS, las identidades y los webhooks funcionan en tu entorno.

Guías

• Almacenamiento
• Facturación
• Configuración del correo
• Analítica