Vídeo tutorial en YouTube

Mira el vídeo completo sobre cómo instalar y usar Formbricks: Plataforma Open Source de Gestión de Experiencia y Encuestas en el canal GENBYTE:

¿Qué es Formbricks: Plataforma Open Source de Gestión de Experiencia y Encuestas?

Formbricks es una plataforma de encuestas y gestión de experiencia (XM) de código abierto que permite recopilar feedback de usuarios en cada punto de su recorrido. Ofrece encuestas in-app, de sitio web, por enlace y por correo electrónico, con un editor sin código, plantillas de mejores prácticas, segmentación de audiencias sin modificar el código de la aplicación y capacidades de análisis preconstruidas. El núcleo está licenciado bajo AGPLv3 y puede autohospedarse mediante Docker sin suscripción. Existe una edición Enterprise con funcionalidades adicionales que requieren clave de licencia. El proyecto está construido con TypeScript, Next.js, React, TailwindCSS, Prisma, Auth.js (Better Auth), Zod y Vitest, y utiliza PostgreSQL, SpiceDB, Cube.js, Redis/Valkey y servicios de correo SMTP.

Características principales

Requisitos del sistema

• Node.js >=24.0.0 <25 (versión fijada en .nvmrc y package.json)
• pnpm 11.7.0 (gestor de paquetes obligatorio)
• Docker y Docker Compose (para pila de desarrollo: PostgreSQL, SpiceDB, MailHog, Valkey, RustFS, Hub, Cube)
• PostgreSQL 15+ (base de datos principal)
• Redis/Valkey 7+ (caché, rate limiting, colas BullMQ)
• Servidor SMTP (para verificación de email, reset de contraseña, invitaciones)
• Almacenamiento S3 compatible (opcional, necesario para subida de archivos en entornos serverless)
• Clave de licencia Enterprise (opcional, para desbloquear módulos EE)

Instalación con Docker Compose

Versión Cloud (SaaS)

La forma más rápida de empezar es usar la oferta alojada en formbricks.com con plan gratuito generoso. Regístrate en https://app.formbricks.com/auth/signup y comienza a crear encuestas sin gestionar infraestructura.

Autohospedado con Docker (producción)

Consulta la guía oficial de autohospedado en https://formbricks.com/docs/self-hosting/deployment. Requiere configurar variables de entorno obligatorias (WEBAPP_URL, BETTER_AUTH_URL, ENCRYPTION_KEY, BETTER_AUTH_SECRET, CRON_SECRET, DATABASE_URL, AUTHZED_*, CUBEJS_*, SMTP_*, etc.) y desplegar los contenedores necesarios: app web, PostgreSQL, SpiceDB, Cube, Redis/Valkey, Hub y worker BullMQ. Los puertos expuestos típicos son 3000 (web), 5432 (PostgreSQL), 50051 (SpiceDB gRPC), 8080 (Hub API), 4000 (Cube API), 6379 (Redis).

Entorno de desarrollo local

Clona el repositorio, instala dependencias y levanta la pila completa con un solo comando. El script pnpm go ejecuta pnpm db:up (genera .env desde .env.example, crea secretos y levanta docker-compose.dev.yml) y luego inicia la app en modo desarrollo.

Acceder al proyecto

Aplicación web (desarrollo)

http://localhost:3000

API Hub (desarrollo)

http://localhost:8080

Cube.js Analytics API (desarrollo)

http://localhost:4000

SpiceDB gRPC (desarrollo)

localhost:50051

MailHog UI (desarrollo)

http://localhost:8025 (puerto por defecto de MailHog en docker-compose.dev.yml)

Producción

Accede mediante el dominio o IP configurado en WEBAPP_URL y BETTER_AUTH_URL. Asegúrate de terminar TLS en un reverse proxy (nginx, Traefik, Cloudflare) y configurar TRUSTED_PROXY_HOP_COUNT según tu topología.

Casos de uso

• Recopilar feedback contextual dentro de aplicaciones SaaS (in-app surveys) para medir NPS, CSAT, CES o validar nuevas funcionalidades.
• Encuestas de sitio web para capturar intención de visitantes, satisfacción de checkout o investigación de mercado.
• Encuestas por enlace distribuidas por email, redes sociales o SMS para estudios puntuales o paneles de usuarios.
• Encuestas transaccionales por email tras eventos clave (compra, onboarding, soporte) con plantillas predefinidas.
• Análisis de sentimiento, emociones y taxonomía de respuestas abiertas mediante IA (proveedores Google, AWS Bedrock, Azure, OpenAI-compatible).
• Automatización de flujos con webhooks hacia Slack, Notion, Zapier, n8n o sistemas internos al recibir respuestas.
• Gestión de experiencia de empleado (eNPS, pulse surveys) en entornos corporativos con SSO (SAML, OIDC, Azure AD, Google, GitHub).
• Cumplimiento de privacidad y soberanía de datos al autohospedar en infraestructura propia bajo AGPLv3.

Configuración avanzada

Variables de entorno críticas

Configura al menos: WEBAPP_URL, BETTER_AUTH_URL, ENCRYPTION_KEY (openssl rand -hex 32), BETTER_AUTH_SECRET (openssl rand -hex 32), CRON_SECRET (openssl rand -hex 32), DATABASE_URL (postgresql://…), AUTHZED_ENDPOINT, AUTHZED_TOKEN, AUTHZED_SYSTEM_KEY, AUTHZED_CONSISTENCY=fully_consistent, CUBEJS_API_URL, CUBEJS_API_SECRET, SMTP_HOST, SMTP_PORT, MAIL_FROM, MAIL_FROM_NAME. Desactiva EMAIL_VERIFICATION_DISABLED=1 y PASSWORD_RESET_DISABLED=1 solo si no tienes SMTP.

Autohospedado con Docker Compose (perfil producción)

La documentación oficial en formbricks.com/docs/self-hosting/deployment describe el compose de producción. Debes proveer imágenes para: formbricks/app (web), postgres, spicedb, cube, valkey/redis, hub, hub-worker, hub-migrate, y opcionalmente taxonomy, qwen/vllm para IA. Usa secretos fuertes para ENCRYPTION_KEY, BETTER_AUTH_SECRET, CRON_SECRET, CUBEJS_API_SECRET, AUTHZED_TOKEN, TAXONOMY_SERVICE_TOKEN, HUB_INTERNAL_API_TOKEN. Habilita perfiles COMPOSE_PROFILES=taxonomy,qwen si usas IA autohospedada.

Autenticación y SSO empresarial

Soporta GitHub, Google, Azure AD, OIDC genérico y SAML. Configura *_CLIENT_ID, *_CLIENT_SECRET, *_TENANT_ID (Azure), OIDC_ISSUER, SAML_DATABASE_URL. Para asignación automática de organizaciones en SSO usa AUTH_SSO_DEFAULT_ORGANIZATION_ID (CUID2 válido) y AUTH_SSO_DEFAULT_ORGANIZATION_ROLE (owner, manager, member, billing). Role Management es feature Enterprise.

IA y taxonomía (beta)

Habilita proveedor AI_PROVIDER (google, aws, azure, openai-compatible) y AI_MODEL. Para Qwen/vLLM local: COMPOSE_PROFILES=qwen,taxonomy, AI_PROVIDER=openai-compatible, AI_MODEL=qwen3-14b-awq, AI_OPENAI_COMPATIBLE_BASE_URL=http://vllm:8000/v1. Taxonomía requiere TAXONOMY_LLM_PROVIDER, TAXONOMY_LLM_MODEL, TAXONOMY_LLM_BASE_URL. Enriquecimientos Hub (sentimiento, emociones, traducción) necesitan SENTIMENT_PROVIDER, EMOTIONS_PROVIDER, TRANSLATION_PROVIDER con sus claves.

Almacenamiento S3 y assets

Define S3_ACCESS_KEY, S3_SECRET_KEY, S3_REGION, S3_BUCKET_NAME, S3_ENDPOINT_URL (para Storj, MinIO, etc.), S3_FORCE_PATH_STYLE=1 si endpoint no es AWS. PUBLIC_URL permite servir rutas de cliente desde dominio distinto a WEBAPP_URL. ASSET_PREFIX_URL para servir JS/CSS desde CDN.

Observabilidad y telemetría

OpenTelemetry: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES, OTEL_LOGS_ENABLED=1. Sentry: SENTRY_DSN, SENTRY_AUTH_TOKEN (build), SENTRY_ENVIRONMENT. Prometheus: PROMETHEUS_ENABLED=1, PROMETHEUS_EXPORTER_PORT. Telemetría de uso: TELEMETRY_DISABLED=1 para desactivar (ignorado si hay licencia EE).

Rate limiting y seguridad

TRUSTED_PROXY_HOP_COUNT (default 1) según proxies delante de la app. RATE_LIMITING_DISABLED=1 para desactivar. DANGEROUSLY_ALLOW_WEBHOOK_INTERNAL_URLS=1 permite webhooks a IPs privadas (riesgo SSRF). WEBHOOK_DELIVERY_TIMEOUT_MS (1000-30000). RECAPTCHA/Turnstile en signup. PASSWORD_HIBP_CHECK_DISABLED=1 en redes aisladas.

Gestión y mantenimiento

Actualización de imágenes Docker

Descarga las últimas imágenes y reinicia los contenedores. Verifica notas de release en GitHub para migraciones de BD o cambios en variables de entorno.

Migraciones de base de datos

Las migraciones Prisma se aplican automáticamente al arrancar la app web. Para entornos controlados, ejecuta pnpm db:migrate:deploy en la imagen de la app antes de iniciar el servicio principal.

Backfill y mantenimiento de SpiceDB

Comandos CLI para autorización: authzed:backfill (reescribe relaciones), authzed:outbox (procesa outbox), authzed:schema (aplica esquema), authzed:upgrade (migra versión). Requieren .env cargado.

Limpieza de recursos de desarrollo

Detiene y elimina contenedores, volúmenes y redes de docker-compose.dev.yml. Útil para resetear estado local.

Rotación de secretos

Regenera ENCRYPTION_KEY, BETTER_AUTH_SECRET, CRON_SECRET, CUBEJS_API_SECRET, AUTHZED_TOKEN, TAXONOMY_SERVICE_TOKEN, HUB_INTERNAL_API_TOKEN y actualiza en .env y gestor de secretos. Reinicia todos los servicios tras el cambio.

Logs y depuración

LOG_LEVEL=debug|info|warn|error|fatal. DEBUG_SHOW_RESET_LINK=1 muestra enlaces de reset en consola del servidor. BULLMQ_WORKER_ENABLED=0 desactiva workers internos (usar deployment separado). AUDIT_LOG_ENABLED=1 y AUDIT_LOG_GET_USER_IP=1 activan auditoría.

Stack técnico

• TypeScript
• Next.js (App Router, React Server Components)
• React
• TailwindCSS
• Prisma ORM
• Auth.js (Better Auth)
• Zod
• Vitest
• Playwright (E2E)
• Turborepo (monorepo)
• pnpm (workspaces)
• PostgreSQL
• SpiceDB (AuthZed) – autorización
• Cube.js – capa semántica analítica
• Redis/Valkey – caché, colas BullMQ, rate limiting
• MailHog (dev) / SMTP (prod) – email
• RustFS / S3 compatible – almacenamiento objetos
• Docker / Docker Compose
• Node.js >=24

Apoya el canal GENBYTE

Sígueme en mis redes sociales