Skip to content
Klutch.sh Docs

Deploying Formbricks

Introduction

Formbricks is a powerful open-source experience management platform that enables developers and product teams to collect qualitative user feedback through in-app surveys, link surveys, and website surveys. Built with modern technologies like Next.js, React, and PostgreSQL, Formbricks provides an alternative to proprietary tools like Typeform and Qualtrics, giving you full control over your data and user insights.

Whether you’re building a SaaS product and need to understand user behavior, running customer research, or collecting feedback at scale, Formbricks offers a flexible, self-hosted solution. Deploying Formbricks on Klutch.sh gives you a production-ready infrastructure with automatic deployments from GitHub, persistent storage for your data, and the ability to scale as your user base grows.

This comprehensive guide walks you through deploying Formbricks on Klutch.sh using a Dockerfile, from initial setup and installation to production configuration, database management, and scaling strategies.

Prerequisites

Before you begin deploying Formbricks on Klutch.sh, ensure you have:

  • A Klutch.sh account with access to the dashboard
  • A GitHub account with a repository for your Formbricks deployment
  • Basic familiarity with Docker, environment variables, and PostgreSQL
  • (Recommended) A PostgreSQL database instance for production use

Understanding Formbricks Architecture

Formbricks consists of several key components:

  • Web Application: A Next.js application that serves the dashboard and admin interface
  • API Server: RESTful API for managing surveys, responses, and integrations
  • Database: PostgreSQL database for storing survey data, user information, and responses
  • File Storage: Storage for uploaded files, images, and other assets

When deploying on Klutch.sh, you’ll configure these components using environment variables and persistent volumes to ensure your data persists across deployments.

Getting Started: Sample Formbricks Application

Let’s create a basic Formbricks deployment setup that you can customize for your needs.

Step 1: Create Your Project Structure

Create a new directory for your Formbricks deployment:

Terminal window
mkdir formbricks-deployment
cd formbricks-deployment

Step 2: Create a Dockerfile

Create a Dockerfile in your project root. This Dockerfile will set up Formbricks with all necessary dependencies:

# Use Node.js LTS version as base image
FROM node:20-alpine AS base


# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat openssl
WORKDIR /app


# Install dependencies based on the preferred package manager
COPY package.json package-lock.json* ./
RUN npm ci


# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .


# Set environment variables for build
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production


# Build the application
RUN npm run build


# Production image, copy all the files and run the app
FROM base AS runner
WORKDIR /app


ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1


RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs


# Copy built application
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static


# Set correct permissions
RUN chown -R nextjs:nodejs /app


USER nextjs


EXPOSE 3000


ENV PORT=3000
ENV HOSTNAME="0.0.0.0"


CMD ["node", "server.js"]

Step 3: Alternative - Using Official Formbricks Image

If you prefer to use the official Formbricks Docker image, create a simpler Dockerfile:

FROM formbricks/formbricks:latest


# Set working directory
WORKDIR /app


# The official image already includes all necessary configurations
# You can add custom scripts or configurations here if needed


EXPOSE 3000


# The entrypoint is already configured in the base image

Step 4: Create Environment Configuration Template

Create a .env.example file to document required environment variables:

Terminal window
# Database Configuration
DATABASE_URL=postgresql://user:password@host:5432/formbricks


# Application Settings
WEBAPP_URL=https://example-app.klutch.sh
NEXTAUTH_SECRET=your-secure-random-string-here
NEXTAUTH_URL=https://example-app.klutch.sh


# Email Configuration (Optional)
MAIL_FROM=noreply@yourdomain.com
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE_ENABLED=0
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key


# Storage Configuration (Optional)
# For file uploads - use S3-compatible storage or persistent volumes
# S3_ACCESS_KEY=your-access-key
# S3_SECRET_KEY=your-secret-key
# S3_REGION=us-east-1
# S3_BUCKET_NAME=formbricks-uploads


# Other Settings
CRON_SECRET=your-cron-secret
ENCRYPTION_KEY=your-encryption-key

Step 5: Initialize Git Repository

Initialize a Git repository and push to GitHub:

Terminal window
git init
git add .
git commit -m "Initial Formbricks deployment setup"
git remote add origin https://github.com/your-username/formbricks-deployment.git
git push -u origin main

Deploying to Klutch.sh

Now that you have your Formbricks application prepared, let’s deploy it to Klutch.sh. Klutch.sh will automatically detect the Dockerfile in your repository root and use it to build your application.

Deployment Steps

    1. Create a New Project

      Log in to the Klutch.sh dashboard and create a new project. Give your project a descriptive name like “Formbricks Production”.

    2. Set Up PostgreSQL Database

      Before deploying the app, you’ll need a PostgreSQL database. You can either:

      • Use a managed PostgreSQL service like Supabase, Neon, or AWS RDS
      • Deploy PostgreSQL on Klutch.sh (see database deployment guides)

      Note your database connection string in the format:

      postgresql://username:password@hostname:5432/database_name

    3. Create Persistent Volume

      Create a persistent volume in Klutch.sh for storing uploaded files and application data:

      • Navigate to your project in the Klutch.sh dashboard
      • Go to the Volumes section
      • Create a new volume with a mount path of /app/uploads
      • Set the size based on your expected storage needs (start with 10GB minimum)

      This ensures that user uploads and generated files persist across deployments. For more details, see the Volumes documentation.

    4. Create New App

      Create a new app within your project:

      • Name: Give your app a name like “formbricks-app”
      • Repository: Select your GitHub repository containing the Dockerfile
      • Branch: Choose your main branch (typically main or master)
      • Traffic Type: Select HTTP (Formbricks is a web application)
      • Internal Port: Set to 3000 (this is the port Formbricks listens on inside the container)
      • Region: Choose the region closest to your users
      • Compute: Start with a medium instance (2GB RAM, 1 vCPU minimum recommended)
      • Instances: Start with 1 instance, scale up as needed

    5. Configure Environment Variables

      Add the following environment variables in your app settings. These are critical for Formbricks to function properly:

      Required Variables:

      • DATABASE_URL: Your PostgreSQL connection string
      • NEXTAUTH_SECRET: Generate a secure random string (use openssl rand -base64 32)
      • NEXTAUTH_URL: Your app’s public URL (e.g., https://example-app.klutch.sh)
      • WEBAPP_URL: Same as NEXTAUTH_URL
      • CRON_SECRET: Another secure random string for scheduled tasks
      • ENCRYPTION_KEY: Secure string for encrypting sensitive data (use openssl rand -hex 32)

      Optional but Recommended:

      • MAIL_FROM: Email address for sending notifications
      • SMTP_HOST: SMTP server hostname
      • SMTP_PORT: SMTP server port
      • SMTP_USER: SMTP username
      • SMTP_PASSWORD: SMTP password (mark as secret)

      Mark sensitive values like passwords and keys as “secret” to prevent them from appearing in logs.

    6. Attach Persistent Volume

      In your app settings, attach the volume you created earlier:

      • Mount path: /app/uploads
      • Select the volume you created in step 3

      This ensures uploaded files and generated content persist across deployments.

    7. Deploy Your Application

      Click Create to start the deployment. Klutch.sh will:

      • Clone your GitHub repository
      • Detect the Dockerfile automatically
      • Build the Docker image
      • Deploy your container with the configured settings
      • Expose your app at a URL like example-app.klutch.sh

    8. Monitor Deployment

      Watch the build logs to ensure everything deploys successfully. The initial build may take 5-10 minutes depending on your dependencies.

    9. Access Your Formbricks Instance

      Once deployed, visit your app’s URL (e.g., https://example-app.klutch.sh). You should see the Formbricks setup wizard on first launch. Follow the on-screen instructions to:

      • Create your admin account
      • Configure your organization
      • Set up your first survey

Database Configuration

Formbricks requires PostgreSQL 12 or higher. Here’s how to properly configure your database:

Database Connection

Your DATABASE_URL should follow this format:

postgresql://username:password@hostname:5432/database_name?sslmode=require

Important considerations:

  • Use SSL connections in production (?sslmode=require)
  • Create a dedicated database user for Formbricks with appropriate permissions
  • Enable connection pooling if using a connection pooler like PgBouncer
  • Set appropriate connection limits based on your instance size

Database Initialization

On first deployment, Formbricks will automatically:

  1. Run database migrations to create necessary tables
  2. Set up initial schema
  3. Create default configurations

You can verify this in your deployment logs. Look for messages like:

[Database] Running migrations...
[Database] Migrations completed successfully

Database Best Practices

  • Backups: Set up automated daily backups of your PostgreSQL database
  • Performance: Monitor query performance and add indexes as your data grows
  • Scaling: Consider read replicas if you have high traffic
  • Security: Never expose your database port publicly; keep it in a private network

Persistent Storage Configuration

Formbricks needs persistent storage for:

  • User-uploaded files (images, documents)
  • Generated reports and exports
  • Cached assets
  • Log files

Using Klutch.sh Volumes

Attach a persistent volume to your app at /app/uploads:

  1. In your app settings, create or attach a volume
  2. Set the mount path to /app/uploads
  3. Choose an appropriate size (recommended: 10GB minimum, scale based on usage)

Using S3-Compatible Storage (Alternative)

For larger deployments or better scalability, use S3-compatible storage:

Add these environment variables:

Terminal window
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1
S3_BUCKET_NAME=formbricks-uploads
S3_ENDPOINT_URL=https://s3.amazonaws.com  # Optional, for S3-compatible services

This offloads file storage to object storage, reducing container disk usage.

Environment Variables Reference

Here’s a comprehensive list of environment variables you can configure:

Core Application Settings

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string
NEXTAUTH_SECRETYesSecret for NextAuth.js session encryption
NEXTAUTH_URLYesFull URL where your app is hosted
WEBAPP_URLYesSame as NEXTAUTH_URL
CRON_SECRETYesSecret for securing cron job endpoints
ENCRYPTION_KEYYesKey for encrypting sensitive data

Email Configuration

VariableRequiredDescription
MAIL_FROMNoSender email address
SMTP_HOSTNoSMTP server hostname
SMTP_PORTNoSMTP server port (typically 587 or 465)
SMTP_SECURE_ENABLEDNoSet to 1 for SSL/TLS
SMTP_USERNoSMTP authentication username
SMTP_PASSWORDNoSMTP authentication password

Storage Configuration

VariableRequiredDescription
S3_ACCESS_KEYNoS3 or compatible service access key
S3_SECRET_KEYNoS3 or compatible service secret key
S3_REGIONNoAWS region or compatible service region
S3_BUCKET_NAMENoBucket name for file storage
S3_ENDPOINT_URLNoCustom endpoint for S3-compatible services

Optional Settings

VariableRequiredDescription
PRIVACY_URLNoLink to your privacy policy
TERMS_URLNoLink to your terms of service
IMPRINT_URLNoLink to your imprint/legal notice
GITHUB_AUTH_ENABLEDNoEnable GitHub OAuth (0 or 1)
GOOGLE_AUTH_ENABLEDNoEnable Google OAuth (0 or 1)
SIGNUP_DISABLEDNoDisable public signups (0 or 1)
INVITE_DISABLEDNoDisable team invites (0 or 1)

Custom Domain Configuration

To use your own domain with Formbricks:

  1. Add Custom Domain in Klutch.sh

    • Navigate to your app in the Klutch.sh dashboard
    • Go to the Domains section
    • Add your custom domain (e.g., surveys.yourdomain.com)
    • Klutch.sh will provide DNS configuration instructions

  2. Update DNS Records

    In your domain provider’s DNS settings:

    • Add an A record or CNAME record as instructed by Klutch.sh
    • Wait for DNS propagation (typically 5-60 minutes)

  3. Update Environment Variables

    Update these variables to reflect your custom domain:

    Terminal window
    NEXTAUTH_URL=https://surveys.yourdomain.com
    WEBAPP_URL=https://surveys.yourdomain.com

  4. Redeploy Application

    Trigger a redeploy for the changes to take effect.

Klutch.sh automatically provisions and manages SSL/TLS certificates for your custom domain, ensuring secure HTTPS connections.

For detailed instructions, see the Custom Domains documentation.

Scaling and Performance Optimization

As your Formbricks usage grows, consider these scaling strategies:

Vertical Scaling

Increase your instance size in the Klutch.sh dashboard:

  • Monitor CPU and memory usage
  • Upgrade to larger instance types as needed
  • Recommended minimum: 2GB RAM, 1 vCPU for production

Horizontal Scaling

For high-traffic deployments:

  • Increase the number of instances in your app settings
  • Klutch.sh automatically load balances between instances
  • Ensure your database can handle multiple connections
  • Use Redis for session storage across multiple instances

Database Optimization

  • Enable connection pooling (use PgBouncer)
  • Monitor slow queries and add indexes
  • Consider read replicas for heavy read workloads
  • Regular VACUUM operations to maintain performance

Caching Strategies

  • Enable Next.js caching features
  • Use Redis for application caching
  • Configure CDN for static assets
  • Implement API response caching where appropriate

Performance Monitoring

Monitor these key metrics:

  • Response time: API and page load times
  • Database performance: Query execution times
  • Memory usage: Container memory consumption
  • CPU usage: Processing load
  • Error rates: Application errors and failed requests

Use Klutch.sh’s built-in monitoring or integrate external tools like Datadog, New Relic, or Sentry.

Security Best Practices

Ensure your Formbricks deployment is secure:

Environment Security

  1. Use Strong Secrets: Generate cryptographically secure random strings for all secret variables

    Terminal window
    openssl rand -base64 32  # For NEXTAUTH_SECRET
    openssl rand -hex 32     # For ENCRYPTION_KEY

  2. Mark Secrets Properly: In Klutch.sh, mark all sensitive environment variables as “secret”

  3. Rotate Credentials: Regularly rotate database passwords, API keys, and secrets

Database Security

  • Use SSL/TLS for database connections
  • Restrict database access to your app’s network
  • Create dedicated database users with minimal required permissions
  • Enable database audit logging

Application Security

  • Keep Formbricks updated to the latest version
  • Enable 2FA for admin accounts
  • Configure CORS properly for your domains
  • Set up rate limiting to prevent abuse
  • Review and limit API access

Network Security

  • Use HTTPS only (Klutch.sh provides this automatically)
  • Configure proper Content Security Policy (CSP) headers
  • Disable unnecessary ports and services
  • Use private networks for internal services

Backup and Recovery

  • Automate daily database backups
  • Test backup restoration procedures regularly
  • Keep backups in a separate region or service
  • Document your disaster recovery plan

Troubleshooting Common Issues

Database Connection Errors

Symptom: App fails to start with “Database connection failed”

Solutions:

  • Verify DATABASE_URL format is correct
  • Ensure database server is accessible from Klutch.sh
  • Check database credentials are correct
  • Verify database accepts SSL connections
  • Check database connection limits aren’t exceeded

Build Failures

Symptom: Docker build fails during deployment

Solutions:

  • Review build logs in Klutch.sh dashboard
  • Ensure all dependencies are specified correctly
  • Verify Node.js version compatibility
  • Check for syntax errors in Dockerfile
  • Ensure sufficient memory for build process

Application Crashes

Symptom: App starts but crashes shortly after

Solutions:

  • Check application logs for error messages
  • Verify all required environment variables are set
  • Ensure database migrations completed successfully
  • Check memory limits aren’t being exceeded
  • Verify persistent volumes are mounted correctly

File Upload Issues

Symptom: Users can’t upload files

Solutions:

  • Verify persistent volume is attached correctly
  • Check volume has sufficient free space
  • Ensure app has write permissions to upload directory
  • If using S3, verify credentials and bucket permissions
  • Check file size limits in your configuration

Email Sending Problems

Symptom: Email notifications don’t send

Solutions:

  • Verify SMTP settings are correct
  • Test SMTP credentials with a mail client
  • Check if your SMTP provider requires allowlisting
  • Verify firewall allows outbound SMTP connections
  • Review email logs for specific error messages

Performance Issues

Symptom: Slow response times or timeouts

Solutions:

  • Monitor resource usage (CPU, memory)
  • Check database query performance
  • Review application logs for bottlenecks
  • Consider scaling up instance size
  • Optimize database queries and add indexes
  • Enable caching where appropriate

Monitoring and Maintenance

Regular Maintenance Tasks

Perform these tasks regularly to keep your Formbricks deployment healthy:

Daily:

  • Monitor application logs for errors
  • Check resource usage (CPU, memory, disk)
  • Verify automated backups completed successfully

Weekly:

  • Review database performance metrics
  • Check for Formbricks updates
  • Monitor storage usage and growth trends
  • Review access logs for suspicious activity

Monthly:

  • Test backup restoration procedures
  • Review and rotate credentials
  • Update dependencies and security patches
  • Analyze usage patterns and plan scaling

Logging

Configure logging for better observability:

  • Application Logs: Available in Klutch.sh dashboard
  • Database Logs: Enable query logging for troubleshooting
  • Access Logs: Monitor HTTP requests and responses
  • Error Tracking: Consider integrating Sentry or similar

Alerts

Set up alerts for critical issues:

  • High error rates
  • Memory or CPU threshold breaches
  • Database connection failures
  • Disk space running low
  • SSL certificate expiration

Upgrading Formbricks

To upgrade to a new version of Formbricks:

  1. Review Changelog: Check the Formbricks releases for breaking changes

  2. Backup Database: Create a database backup before upgrading

  3. Update Docker Image:

    • If using official image: Update version in Dockerfile
    • If building from source: Pull latest code

  4. Test Locally: Test the upgrade in a development environment first

  5. Deploy Update:

    • Push changes to GitHub
    • Klutch.sh will automatically rebuild and deploy

  6. Run Migrations: Formbricks will automatically run database migrations on startup

  7. Verify Deployment: Check logs and test functionality after upgrade

Example Production Configuration

Here’s a complete example of a production-ready Formbricks deployment:

Dockerfile (using official image):

FROM formbricks/formbricks:latest


# Production-ready configuration
WORKDIR /app


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node healthcheck.js || exit 1


EXPOSE 3000


# Use non-root user
USER node

Environment Variables (production):

Terminal window
# Core Settings
DATABASE_URL=postgresql://formbricks:secure_password@postgres.internal:5432/formbricks?sslmode=require
NEXTAUTH_SECRET=your-production-secret-here-min-32-chars
NEXTAUTH_URL=https://surveys.yourdomain.com
WEBAPP_URL=https://surveys.yourdomain.com
CRON_SECRET=another-secure-production-secret
ENCRYPTION_KEY=your-hex-encryption-key-64-chars


# Email Configuration
MAIL_FROM=surveys@yourdomain.com
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE_ENABLED=0
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key


# Storage (S3)
S3_ACCESS_KEY=your-s3-access-key
S3_SECRET_KEY=your-s3-secret-key
S3_REGION=us-east-1
S3_BUCKET_NAME=formbricks-prod-uploads


# Security
SIGNUP_DISABLED=1
INVITE_DISABLED=0


# URLs
PRIVACY_URL=https://yourdomain.com/privacy
TERMS_URL=https://yourdomain.com/terms

Volume Configuration:

  • Mount path: /app/uploads
  • Size: 50GB
  • Backup: Daily automated backups

Instance Configuration:

  • Instance type: 4GB RAM, 2 vCPU
  • Number of instances: 2 (for high availability)
  • Region: Closest to your user base
  • Auto-scaling: Enabled

Resources and Further Reading

Conclusion

Deploying Formbricks on Klutch.sh provides you with a robust, scalable platform for collecting and managing user feedback. With automatic deployments from GitHub, persistent storage, and easy scaling options, you can focus on building great surveys and gathering insights rather than managing infrastructure.

This guide covered everything from basic deployment to production-ready configurations. Start with a simple setup and gradually add features like custom domains, S3 storage, and horizontal scaling as your needs grow. Remember to follow security best practices, maintain regular backups, and keep your Formbricks instance updated.

For additional support or questions, refer to the resources above or reach out to the Klutch.sh community. Happy surveying!