Puesta en marcha

De cero a un BloomX funcionando, en el orden en que conviene hacerlo. Cada paso enlaza con la página que lo detalla.

Lista de verificación#

1. Decide el modelo: usar el backend compartido de otra organización, o desplegar el tuyo (Arquitectura).
2. Crea una base de datos PostgreSQL para el frontend (y otra para el backend si lo despliegas).
3. Crea una cuenta de Resend, verifica tu dominio y obtén una clave de API (Correo: Resend y DNS).
4. Crea un bucket S3-compatible (S3, R2, B2, MinIO) para adjuntos (Almacenamiento).
5. Define las variables de entorno (Variables de entorno).
6. Ejecuta npm run db:ensure contra la base de datos de destino.
7. Despliega (Despliegue).
8. Registra tu dominio en el backend y la clave pública Ed25519 de tu instancia (API del backend).
9. Configura los webhooks de Resend, el DNS y los crons.
10. Pruébalo con el checklist final de esta página.

Desarrollo local#

git clone <tu-repositorio>/bloomx && cd bloomx
npm install                       # postinstall ejecuta prisma generate
cp .env.example .env              # y completa lo mínimo (ver Variables de entorno)
npm run db:ensure                 # crea/actualiza tablas (también corre solo en predev/prebuild/prestart)
npm run dev                       # http://localhost:3000

• Necesitas una versión de Node compatible con Next.js (20 o superior recomendada) y una base PostgreSQL accesible.
• predev, prebuild y prestart ejecutan tsx scripts/ensure-schema.ts, así que las tablas se crean solas. Sin DATABASE_URL solo emite un aviso y sale con código 0.
• Sin S3_ACCESS_KEY/S3_BUCKET el almacenamiento cae a disco local (.gemini/storage): solo para desarrollo.
• Para probar un tema de empresa sin backend usa NEXT_PUBLIC_BLOOMX_THEME_OVERRIDE (Temas).
• Para un entorno E2E totalmente local (Postgres embebido, Resend y backend falsos) ve Operación.

Primer usuario y administración#

1. Define REGISTRATION_KEY (en producción, si falta o vale dev-secret, el registro responde 403) y abre /register.
2. Para acceder a las rutas de administración, añade tu correo a ADMIN_EMAILS: la cuenta debe activar MFA TOTP (obligatorio para administradores) antes de usar api/admin/*.
3. El panel de administración del dominio (marca, tema, landing, extensiones) usa la sesión de manager del backend: entra por /admin/login (o crea el manager y el dominio en /admin/register).

Clave de firma de la instancia (recomendado)#

Sin clave, tu dominio funciona en modo legado (sin EMAIL_RECEIVED, sin services.mail; las extensiones siguen usando sus credenciales y el panel muestra un aviso para registrar la clave). Para el modo firmado:

node scripts/gen-domain-keypair.mjs
# Imprime:
#   BLOOMX_DOMAIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"   <- variable SECRETA del frontend
#   signingPublicKey: <clave pública base64url>                                                    <- se registra en el backend

1. Guarda BLOOMX_DOMAIN_PRIVATE_KEY en el entorno del frontend (nunca en git).
2. Registra la clave pública: signingPublicKey en verify-domain, o POST /api/manager/domain-key con la sesión del manager.
3. Comprueba que el backend ya no responde X-BloomX-Auth: legacy a tus peticiones.

Checklist final#

• GET /api/config del frontend devuelve la marca y las extensiones de tu dominio (no la config por defecto "BloomX Default").
• Puedes registrarte, iniciar sesión y activar MFA.
• Un correo enviado a tu dominio aparece en la bandeja (webhook de Resend + MX).
• Un correo enviado desde BloomX llega y muestra SPF=PASS, DKIM=PASS y DMARC=PASS.
• Adjuntar y descargar un archivo funciona (almacenamiento).
• El cron diario responde 200 con CRON_SECRET (Despliegue).
• Las extensiones que instalaste funcionan (si hay hooks, tu dominio debe estar en modo firmado).