Quick Start Guide

Prerequisites

• Docker and Docker Compose: Install Docker Desktop
• Text Editor: For editing the .env file

Installation

Option 1: Docker Compose (Recommended)

The easiest way to run Formbricks Hub with all dependencies.

1. Download the Configuration

Create a new directory and download the Docker Compose file:

mkdir formbricks-hub && cd formbricks-hub
curl -o compose.yml https://raw.githubusercontent.com/formbricks/hub/main/compose.yml

Or create it manually:

services:
  postgres:
    image: pgvector/pgvector:pg18
    container_name: formbricks_hub_postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: formbricks
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-formbricks_dev}
      POSTGRES_DB: hub
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U formbricks -d hub"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - formbricks_hub
    command: >
      postgres
      -c shared_preload_libraries=vector

  hub:
    image: ghcr.io/formbricks/hub:latest
    container_name: formbricks_hub_api
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://formbricks:${POSTGRES_PASSWORD:-formbricks_dev}@postgres:5432/hub?sslmode=disable
      API_KEY: ${API_KEY:-}
      PORT: ${PORT:-8080}
      LOG_LEVEL: ${LOG_LEVEL:-info}
    ports:
      - "8080:8080"
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:8080/health",
        ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    networks:
      - formbricks_hub

volumes:
  postgres_data:
    driver: local

networks:
  formbricks_hub:
    driver: bridge

2. Configure Environment Variables

Create a .env file in the same directory:

# Required: Secure your PostgreSQL database
POSTGRES_PASSWORD=your_secure_postgres_password_here

# Required: API authentication key
API_KEY=your_secure_api_key_here

# Optional: Server configuration
PORT=8080
LOG_LEVEL=info

Generate secure passwords and API keys:

# For POSTGRES_PASSWORD
openssl rand -base64 32

# For API_KEY
openssl rand -base64 32

3. Start the Services

docker compose up -d

This will:

• Pull the latest Formbricks Hub image from GitHub Container Registry
• Start PostgreSQL with persistent storage
• Start the Hub API on port 8080

4. Run Database Migrations

Migrations are managed with goose. From the project directory with DATABASE_URL set to your Postgres connection string:

# Install goose (if not already: make install-tools)
go install github.com/pressly/goose/v3/cmd/goose@v3.26.0

# Apply migrations
goose -dir migrations postgres "$DATABASE_URL" up

Or use the Makefile (loads DATABASE_URL from .env):

make init-db

You only need to run this once when setting up the database for the first time.

5. Verify Installation

Check that both services are healthy:

docker compose ps

Expected output:

NAME                        STATUS              PORTS
formbricks_hub_api          Up (healthy)        0.0.0.0:8080->8080/tcp
formbricks_hub_postgres     Up (healthy)        0.0.0.0:5432->5432/tcp

Test the health endpoint:

curl http://localhost:8080/health

Expected response:

{ "status": "ok" }

Option 2: Docker Run (Minimal)

If you have an existing PostgreSQL instance, run just the Hub API:

docker run -d \
  --name formbricks-hub \
  -p 8080:8080 \
  -e DATABASE_URL="postgresql://user:password@host:5432/hub?sslmode=disable" \
  -e API_KEY="your-secret-key" \
  -e LOG_LEVEL="info" \
  ghcr.io/formbricks/hub:latest

Warning: Make sure to run migrations before starting the API. From the Hub repo with DATABASE_URL set: make init-db or goose -dir migrations postgres "$DATABASE_URL" up.

Making Your First API Call

1. Create a Feedback Record

curl -X POST http://localhost:8080/v1/feedback-records \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secure_api_key_here" \
  -d '{
    "source_type": "survey",
    "source_id": "my-first-survey",
    "field_id": "q1",
    "field_label": "How satisfied are you?",
    "field_type": "rating",
    "value_number": 5,
    "metadata": {
      "country": "US",
      "device": "desktop"
    }
  }'

All API requests require the Authorization: Bearer <token> header with your configured API_KEY.

Expected response:

{
  "id": "01932c8a-8b9e-7000-8000-000000000001",
  "collected_at": "2025-10-20T12:34:56Z",
  "created_at": "2025-10-20T12:34:56Z",
  "source_type": "survey",
  "source_id": "my-first-survey",
  "field_id": "q1",
  "field_type": "rating",
  "value_number": 5,
  "metadata": {
    "country": "US",
    "device": "desktop"
  }
}

2. Create a Text Feedback Record

curl -X POST http://localhost:8080/v1/feedback-records \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secure_api_key_here" \
  -d '{
    "source_type": "survey",
    "source_id": "my-first-survey",
    "field_id": "q2",
    "field_label": "What can we improve?",
    "field_type": "text",
    "value_text": "The checkout process could be simplified!"
  }'

3. Query Feedback Records

curl "http://localhost:8080/v1/feedback-records?limit=10" \
  -H "Authorization: Bearer your_secure_api_key_here"

Response:

{
  "data": [...],
  "total": 2,
  "limit": 10,
  "offset": 0
}

Configuration

Environment Variables

Variable	Required	Default	Description
DATABASE_URL	No	postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable	PostgreSQL connection string
API_KEY	Yes	-	API authentication key
PORT	No	8080	HTTP server port
LOG_LEVEL	No	info	Log level (debug, info, warn, error)

See full environment variable reference ->

Database Connection String Format

postgresql://username:password@host:port/database?sslmode=disable

For Docker Compose (services in same network):

postgresql://formbricks:password@postgres:5432/hub?sslmode=disable

For external PostgreSQL:

postgresql://user:pass@db.example.com:5432/hub?sslmode=require

Managing the Service

View Logs

# All services
docker compose logs -f

# Just the Hub API
docker compose logs -f hub

# Just PostgreSQL
docker compose logs -f postgres

Stop Services

docker compose down

Stop and Remove Data

Warning: This will delete all stored feedback records.

docker compose down -v

Restart Services

docker compose restart

Update to Latest Version

docker compose pull
docker compose up -d

Next Steps

• Data Model - Understand the feedback record structure
• Authentication - Learn about API security
• API Reference - Explore all endpoints
• Environment Variables - Configure your deployment

Troubleshooting

Port Already in Use

If port 8080 or 5432 is occupied:

# Change ports in .env
PORT=8081

Or modify the port mapping in compose.yml:

ports:
  - "8081:8080" # Host:Container

Container Fails to Start

Check the logs for errors:

docker compose logs hub

Common issues:

• Database not ready: Wait for PostgreSQL healthcheck to pass
• Invalid API key: Ensure API_KEY is set in .env
• Database connection failed: Check DATABASE_URL format

Database Connection Failed

Verify PostgreSQL is running:

docker compose ps postgres

If unhealthy, check PostgreSQL logs:

docker compose logs postgres

Health Check Failing

Check if the service is listening:

docker exec formbricks_hub_api wget -O- http://localhost:8080/health

Cannot Pull Docker Image

Ensure you have access to GitHub Container Registry:

docker pull ghcr.io/formbricks/hub:latest

If authentication is required:

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Data Not Persisting

Verify the volume is mounted:

docker volume ls | grep postgres_data
docker volume inspect formbricks-hub_postgres_data

Getting Help

• GitHub Discussions: Ask questions and share ideas
• GitHub Issues: Report bugs or request features
• API Reference: Interactive documentation