docs: updated documents regarding hub integration

.env.example

@@ -38,6 +38,13 @@ LOG_LEVEL=info
 
 DATABASE_URL='postgresql://postgres:postgres@localhost:5432/formbricks?schema=public'
 
+#################
+#  HUB (DEV)    #
+#################
+# Optional. The dev stack (pnpm db:up / pnpm go) runs Formbricks Hub on port 8080.
+# Override the default Hub API key (default: dev-api-key) when using docker-compose.dev.yml:
+# HUB_API_KEY=
+
 ################
 #  MAIL SETUP  #
 ################

README.md

@@ -169,7 +169,7 @@ Here is what you need to be able to run Formbricks:
 
 ### Local Setup
 
-To get started locally, we've got a [guide to help you](https://formbricks.com/docs/developer-docs/contributing/get-started#local-machine-setup).
+To get started locally, we've got a [guide to help you](https://formbricks.com/docs/developer-docs/contributing/get-started#local-machine-setup). The dev stack (`pnpm db:up` or `pnpm go`) includes [Formbricks Hub](https://github.com/formbricks/hub) on port 8080; optional Hub env vars (e.g. `HUB_API_KEY`) are in `.env.example`. See [docker/README.md](docker/README.md#formbricks-hub) for details.
 
 ### Gitpod Setup
 

charts/formbricks/templates/_helpers.tpl

@@ -7,6 +7,10 @@ It also truncates the name to a maximum of 63 characters and removes trailing hy
 {{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
 {{- end }}
 
+{{- define "formbricks.hubname" -}}
+{{- printf "%s-hub" (include "formbricks.name" .) | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
 
 {{/*
 Define the application version to be used in labels.

charts/formbricks/templates/hub-deployment.yaml

@@ -0,0 +1,55 @@
+{{- if .Values.hub.enabled }}
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "formbricks.hubname" . }}
+  labels:
+    helm.sh/chart: {{ include "formbricks.chart" . }}
+    app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: hub
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+    app.kubernetes.io/part-of: {{ .Values.partOfOverride | default (include "formbricks.name" .) }}
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+      app.kubernetes.io/instance: {{ .Release.Name }}
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: hub
+    spec:
+      {{- if .Values.deployment.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.deployment.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: hub
+          image: {{ .Values.hub.image.repository }}:{{ .Values.hub.image.tag | default "latest" }}
+          imagePullPolicy: {{ .Values.hub.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          {{- if .Values.hub.existingSecret }}
+          envFrom:
+            - secretRef:
+                name: {{ .Values.hub.existingSecret }}
+          {{- end }}
+          {{- if .Values.hub.env }}
+          env:
+            {{- range $key, $value := .Values.hub.env }}
+            - name: {{ $key }}
+              value: {{ $value | quote }}
+            {{- end }}
+          {{- end }}
+          {{- if .Values.hub.resources }}
+          resources:
+            {{- toYaml .Values.hub.resources | nindent 12 }}
+          {{- end }}
+{{- end }}

charts/formbricks/templates/hub-migration-job.yaml

@@ -0,0 +1,45 @@
+{{- if and .Values.hub.enabled .Values.hub.existingSecret }}
+---
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ include "formbricks.hubname" . }}-migration
+  labels:
+    helm.sh/chart: {{ include "formbricks.chart" . }}
+    app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: hub-migration
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+  annotations:
+    helm.sh/hook: pre-install,pre-upgrade
+    helm.sh/hook-weight: "-5"
+    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
+spec:
+  ttlSecondsAfterFinished: {{ .Values.hub.migration.ttlSecondsAfterFinished | default 300 }}
+  backoffLimit: {{ .Values.hub.migration.backoffLimit | default 3 }}
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: hub-migration
+    spec:
+      restartPolicy: Never
+      {{- if .Values.deployment.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.deployment.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: hub-migrate
+          image: {{ .Values.hub.image.repository }}:{{ .Values.hub.image.tag | default "latest" }}
+          imagePullPolicy: {{ .Values.hub.image.pullPolicy }}
+          command:
+            - sh
+            - -c
+            - |
+              /usr/local/bin/goose -dir /app/migrations postgres "$DATABASE_URL" up && \
+              /usr/local/bin/river migrate-up --database-url "$DATABASE_URL"
+          envFrom:
+            - secretRef:
+                name: {{ .Values.hub.existingSecret }}
+{{- end }}

charts/formbricks/templates/hub-service.yaml

@@ -0,0 +1,24 @@
+{{- if .Values.hub.enabled }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "formbricks.hubname" . }}
+  labels:
+    helm.sh/chart: {{ include "formbricks.chart" . }}
+    app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: hub
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+    app.kubernetes.io/part-of: {{ .Values.partOfOverride | default (include "formbricks.name" .) }}
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/name: {{ include "formbricks.hubname" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+  ports:
+    - name: http
+      port: 8080
+      targetPort: 8080
+      protocol: TCP
+{{- end }}

charts/formbricks/values.yaml

@@ -304,6 +304,36 @@ serviceMonitor:
       path: /metrics
       port: metrics
 
+##########################################################
+# Hub API Configuration
+# Formbricks Hub image: ghcr.io/formbricks/hub
+##########################################################
+hub:
+  enabled: true
+
+  image:
+    repository: "ghcr.io/formbricks/hub"
+    tag: "latest"
+    pullPolicy: IfNotPresent
+
+  # Secret containing API_KEY and DATABASE_URL for Hub. Use the same app secret (or same DATABASE_URL) to share the Formbricks database.
+  existingSecret: ""
+
+  # Optional env vars (non-secret). Use existingSecret for API_KEY and DATABASE_URL.
+  env: {}
+
+  # Migration job runs goose + river before Hub API starts (pre-install/pre-upgrade hook). Requires existingSecret with DATABASE_URL.
+  migration:
+    ttlSecondsAfterFinished: 300
+    backoffLimit: 3
+
+  resources:
+    limits:
+      memory: 512Mi
+    requests:
+      memory: 256Mi
+      cpu: "100m"
+
 ##########################################################
 # PostgreSQL Configuration
 ##########################################################

docker-compose.dev.yml

@@ -1,14 +1,19 @@
 services:
+  # PostgreSQL must load the vector library so Hub (and Formbricks) can use the pgvector extension.
   postgres:
     image: pgvector/pgvector:pg17
     volumes:
       - postgres:/var/lib/postgresql/data
+      - ./docker/postgres-init-dev:/docker-entrypoint-initdb.d:ro
     environment:
       - POSTGRES_DB=postgres
       - POSTGRES_USER=postgres
       - POSTGRES_PASSWORD=postgres
     ports:
       - 5432:5432
+    command: >
+      postgres
+      -c shared_preload_libraries=vector
 
   mailhog:
     image: arjenz/mailhog
@@ -36,6 +41,36 @@ services:
     volumes:
       - minio-data:/data
 
+  # Run Hub DB migrations (goose + river) before the API starts. Idempotent; runs on every compose up.
+  hub-migrate:
+    image: ghcr.io/formbricks/hub:latest
+    restart: "no"
+    entrypoint: ["sh", "-c"]
+    command: ["if [ -x /usr/local/bin/goose ] && [ -x /usr/local/bin/river ]; then /usr/local/bin/goose -dir /app/migrations postgres \"$$DATABASE_URL\" up && /usr/local/bin/river migrate-up --database-url \"$$DATABASE_URL\"; else echo 'Migration tools (goose/river) not in image, skipping migrations.'; fi"]
+    environment:
+      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public
+    depends_on:
+      - postgres
+
+  # Formbricks Hub API (ghcr.io/formbricks/hub). Shares the same Postgres database as Formbricks by default.
+  hub:
+    image: ghcr.io/formbricks/hub:latest
+    depends_on:
+      hub-migrate:
+        condition: service_completed_successfully
+    ports:
+      - "8080:8080"
+    environment:
+      API_KEY: ${HUB_API_KEY:-dev-api-key}
+      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public&sslmode=disable
+      # Explicit Postgres env so migrations and any libpq fallback use the service host, not localhost
+      PGHOST: postgres
+      PGPORT: "5432"
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      PGDATABASE: postgres
+      PGSSLMODE: disable
+
 volumes:
   postgres:
     driver: local

docker/README.md

@@ -27,3 +27,13 @@ The script will prompt you for the following information:
 3. **Domain Name**: Enter the domain name that Traefik will use to create the SSL certificate and forward requests to Formbricks.
 
 That's it! After running the command and providing the required information, visit the domain name you entered, and you should see the Formbricks home wizard!
+
+## Formbricks Hub
+
+The stack includes the [Formbricks Hub](https://github.com/formbricks/hub) API (`ghcr.io/formbricks/hub`). Hub shares the same database as Formbricks by default.
+
+- **Migrations**: A `hub-migrate` service runs Hub’s database migrations (goose + river) before the Hub API starts. It runs on every `docker compose up` and is idempotent.
+- **Production** (`docker/docker-compose.yml`): Set `HUB_API_KEY` (required). Override `HUB_DATABASE_URL` only if you want Hub to use a separate database (default is the same Formbricks Postgres URL).
+- **Development** (`docker-compose.dev.yml`): Hub uses the same Postgres database; `API_KEY` defaults to `dev-api-key` (override with `HUB_API_KEY`).
+
+Hub listens on port **8080**.

docker/docker-compose.yml

@@ -245,6 +245,33 @@ services:
       - ./saml-connection:/home/nextjs/apps/web/saml-connection
     <<: *environment
 
+  # Run Hub DB migrations (goose + river) before the API starts. Uses same image; migrations are idempotent.
+  hub-migrate:
+    image: ghcr.io/formbricks/hub:latest
+    restart: "no"
+    entrypoint: ["sh", "-c"]
+    command: ["if [ -x /usr/local/bin/goose ] && [ -x /usr/local/bin/river ]; then /usr/local/bin/goose -dir /app/migrations postgres \"$$DATABASE_URL\" up && /usr/local/bin/river migrate-up --database-url \"$$DATABASE_URL\"; else echo 'Migration tools (goose/river) not in image, skipping migrations.'; fi"]
+    environment:
+      DATABASE_URL: ${HUB_DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/formbricks?schema=public}
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  # Formbricks Hub API (ghcr.io/formbricks/hub). Set HUB_API_KEY. By default shares the Formbricks database; set HUB_DATABASE_URL to use a separate DB.
+  hub:
+    restart: always
+    image: ghcr.io/formbricks/hub:latest
+    depends_on:
+      hub-migrate:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    ports:
+      - "8080:8080"
+    environment:
+      API_KEY: ${HUB_API_KEY:?HUB_API_KEY is required to run Hub}
+      DATABASE_URL: ${HUB_DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/formbricks?schema=public}
+
 volumes:
   postgres:
     driver: local