Formbricks on StartOS

Upstream docs: https://formbricks.com/docs

Everything not listed in this document should behave the same as upstream Formbricks 5.1.2. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Formbricks is an open-source experience management platform for building surveys, forms, and feedback workflows — a self-hosted alternative to Qualtrics and Typeform. This package bundles the Formbricks app together with the PostgreSQL and Redis it requires into a single self-contained StartOS service with no external dependencies. It is built from the upstream ghcr.io/formbricks/formbricks image.

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Actions
• Backups and Restore
• Health Checks
• Limitations and Differences
• What Is Unchanged from Upstream
• Contributing
• Quick Reference for AI Consumers

---

Image and Container Runtime

All images are upstream and unmodified. Each runs in its own subcontainer, and all subcontainers share the package network namespace, so every component reaches the others over 127.0.0.1.

Component	Image	Role
formbricks	ghcr.io/formbricks/formbricks:5.1.2	Next.js app server (the interface StartOS exposes)
postgres	pgvector/pgvector:pg18	Bundled database (pgvector-enabled, as Formbricks requires)
redis	redis:7-alpine	Bundled cache / rate-limiting / audit-log store

• Architectures: x86_64, aarch64 (all three images are multi-arch).
• Entrypoints: All three use their image's default entrypoint via useEntrypoint(). The Formbricks image's start.sh applies pending database migrations (SKIP_STARTUP_MIGRATION is left unset) and then starts the Next.js server, so migrate-then-serve happens in one step on every boot.
• A short prepare-uploads oneshot runs as root before the app starts to make the uploads volume writable by the image's non-root nextjs user (uid 1001).

---

Volume and Data Layout

A single main volume holds everything, under separate subpaths:

Path on main	Mount Point	Purpose
postgres/	/var/lib/postgresql/data	PostgreSQL data (PGDATA=.../pgdata)
uploads/	/home/nextjs/uploads	Locally-uploaded files (UPLOADS_DIR)
store.json	—	StartOS-managed secrets + SMTP selection

Redis runs without a volume — it holds only caches, rate-limit counters, and audit-log buffers, and rebuilds its state on boot.

---

Installation and First-Run Flow

Formbricks has no preset administrator account. On install, StartOS generates and persists the instance secrets (database password, NEXTAUTH_SECRET, ENCRYPTION_KEY, CRON_SECRET, CUBEJS_API_SECRET) into store.json. Once the Web Interface health check is green, open the web interface and create the first account — the first account to sign up becomes the owner/administrator of the instance.

Email verification is disabled (EMAIL_VERIFICATION_DISABLED=1) so the first signup works before any SMTP is configured. Add SMTP later with the Configure SMTP action.

---

Configuration Management

StartOS-Managed (env vars / actions)	Upstream-Managed (in-app)
DATABASE_URL, REDIS_URL (point at the bundled Postgres/Redis)	Organizations, projects, surveys, team members
NEXTAUTH_SECRET, ENCRYPTION_KEY, CRON_SECRET, CUBEJS_API_SECRET	Survey content, branding, response/insight views
WEBAPP_URL / NEXTAUTH_URL (set to the primary StartOS address)	API keys, webhooks, integrations
AUTH_TRUST_HOST=1, EMAIL_VERIFICATION_DISABLED=1
SMTP (MAIL_FROM, SMTP_*) via the Configure SMTP action

Secrets are generated once on install and are not user-editable.

---

Network Access and Interfaces

Interface	Port	Protocol	Purpose
Web UI	3000	HTTP	Formbricks web app

Access methods: LAN IP, <hostname>.local, Tor .onion, and custom domains all work. Because Formbricks bakes one origin into outgoing links, WEBAPP_URL is set to the first address StartOS assigns; survey-share and email links use that origin. AUTH_TRUST_HOST=1 lets Auth.js derive sign-in callback URLs from the request, so signing in works on every origin.

---

Actions

Action	Purpose	Visibility	Availability	Input	Output
Configure SMTP	Set SMTP for verification/invitation/notification emails (disabled / system / custom). Persisted to store.json; the app restarts with the new SMTP_* settings.	Enabled	Any status	SMTP selection	—

Without SMTP configured, email-based features (verification, invites, password reset) are unavailable; surveys and responses work regardless.

---

Backups and Restore

Included in backup: the main volume — i.e. the PostgreSQL database, uploaded files, and store.json (secrets + SMTP selection).

Not backed up: Redis state (caches / rate-limit / audit buffers — transient by design).

Restore behavior: the volume is fully restored before the service starts; secrets are not regenerated on restore.

---

Health Checks

Check	Method	Grace	Messages
Database	Port listening (5432)	—	"PostgreSQL is ready" / "PostgreSQL is not responding"
Cache	Port listening (6379)	—	"Redis is ready" / "Redis is not responding"
Web Interface	Port listening (3000)	180 s	"Formbricks is ready" / "Formbricks is starting"

The app daemon requires Postgres and Redis to be ready first, since the image runs migrations on startup without waiting for the database itself.

---

Limitations and Differences

1. Companion services (Cube & Hub) are not bundled. Formbricks v5 ships a Cube analytics semantic-layer and a Hub service. To keep this package light, both are omitted: CUBEJS_API_URL and HUB_API_URL point at unused local URLs (only their format is validated; they are contacted lazily) and their secret/key reuse a generated value. Survey building and response collection work normally; Cube-backed analytics/insights are unavailable.
2. Single canonical origin for links. WEBAPP_URL is the first StartOS address, so survey-share and email links use that origin even when you access the app from another (e.g. .onion). Sign-in still works on all origins.
3. No SMTP by default. Email-dependent features are off until you run the Configure SMTP action; email verification is disabled to allow first signup.
4. Enterprise Edition features require a Formbricks license key and are not configured here.

---

What Is Unchanged from Upstream

• The Formbricks application image, version 5.1.2, run unmodified.
• Survey/form building, link and in-app surveys, response collection, team and project management, API keys, webhooks, and integrations.
• Database schema and migrations (applied by the image's own startup script).
• All in-app settings reachable from the Formbricks UI.

---

Contributing

See CONTRIBUTING.md for build instructions and development workflow.

---

Quick Reference for AI Consumers

package_id: formbricks
upstream_version: 5.1.2
image: ghcr.io/formbricks/formbricks:5.1.2
architectures: [x86_64, aarch64]
volumes:
  main:
    postgres: /var/lib/postgresql/data
    uploads: /home/nextjs/uploads
    store.json: StartOS-managed secrets + SMTP selection
ports:
  ui: 3000
dependencies: none
bundled_services:
  - pgvector/pgvector:pg18
  - redis:7-alpine
startos_managed_env_vars:
  - DATABASE_URL
  - REDIS_URL
  - NEXTAUTH_SECRET
  - ENCRYPTION_KEY
  - CRON_SECRET
  - CUBEJS_API_URL
  - CUBEJS_API_SECRET
  - HUB_API_URL
  - HUB_API_KEY
  - WEBAPP_URL
  - NEXTAUTH_URL
  - AUTH_TRUST_HOST
  - EMAIL_VERIFICATION_DISABLED
  - UPLOADS_DIR
  - SMTP_* (when configured via action)
actions:
  - manage-smtp