Self-Hosting HeyForm with Docker Compose

What Is HeyForm?

HeyForm is an open-source form builder that creates conversational, one-question-at-a-time forms — the same interaction pattern that made Typeform popular. Unlike traditional form builders that dump 20 fields on a single page, HeyForm presents questions sequentially with smooth transitions, boosting completion rates.

Updated February 2026: Verified with latest Docker images and configurations.

It supports 40+ field types including ratings, opinion scales, file uploads, payment fields, and conditional logic. Self-hosting means your form submissions stay on your server — no third-party data processors touching your respondents’ answers.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 1 GB of free RAM (minimum)
• 5 GB of free disk space
• A domain name (optional, for public forms)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  heyform:
    image: heyform/community-edition:v0.1.0
    container_name: heyform
    restart: unless-stopped
    depends_on:
      mongo:
        condition: service_healthy
      keydb:
        condition: service_healthy
    ports:
      - "9157:9157"
    environment:
      - APP_HOMEPAGE_URL=${APP_HOMEPAGE_URL}
      - SESSION_KEY=${SESSION_KEY}
      - FORM_ENCRYPTION_KEY=${FORM_ENCRYPTION_KEY}
      - MONGO_URI=mongodb://mongo:27017/heyform
      - REDIS_HOST=keydb
      - REDIS_PORT=6379
    volumes:
      - heyform-uploads:/app/packages/twenty-server/static/upload
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9157/health/ready"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 30s

  mongo:
    image: mongo:7
    container_name: heyform-mongo
    restart: unless-stopped
    volumes:
      - heyform-mongo:/data/db
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  keydb:
    image: eqalpha/keydb:x86_64_v6.3.4
    container_name: heyform-keydb
    restart: unless-stopped
    command: keydb-server --appendonly yes --protected-mode no
    volumes:
      - heyform-keydb:/data
    healthcheck:
      test: ["CMD", "keydb-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  heyform-uploads:
  heyform-mongo:
  heyform-keydb:

Create a .env file alongside:

# URL where HeyForm will be accessed (must match exactly)
APP_HOMEPAGE_URL=http://localhost:9157

# Session encryption key — generate with: openssl rand -hex 32
SESSION_KEY=CHANGE_ME_GENERATE_A_REAL_KEY

# Form data encryption key — generate with: openssl rand -hex 32
FORM_ENCRYPTION_KEY=CHANGE_ME_GENERATE_A_REAL_KEY

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server:9157 in your browser
2. Create your admin account with email and password
3. Create a workspace — this groups your forms and team members
4. Click Create Form to build your first conversational form

The form editor is drag-and-drop. Add fields from the left panel, configure logic rules, and preview in real-time.

Configuration

Setting	Variable	Description
Homepage URL	APP_HOMEPAGE_URL	Must exactly match user-facing URL
Session key	SESSION_KEY	Encrypts user sessions
Encryption key	FORM_ENCRYPTION_KEY	Encrypts form submission data
Session timeout	SESSION_MAX_AGE	Default: 15 days
Google fonts	ENABLE_GOOGLE_FONTS	Default: disabled
Upload types	UPLOAD_FILE_TYPES	Allowed file extensions

Email Notifications

Configure SMTP for form submission notifications:

environment:
  - SMTP_FROM=HeyForm <[email protected]>
  - SMTP_HOST=smtp.gmail.com
  - SMTP_PORT=465
  - [email protected]
  - SMTP_PASSWORD=your-app-password
  - SMTP_SECURE=true

Google OAuth Login

environment:
  - GOOGLE_LOGIN_CLIENT_ID=your-client-id
  - GOOGLE_LOGIN_CLIENT_SECRET=your-client-secret

Advanced Configuration

Spam Protection

Add Akismet or reCAPTCHA to protect public forms:

environment:
  - AKISMET_KEY=your-akismet-key
  # OR
  - GOOGLE_RECAPTCHA_KEY=your-site-key
  - GOOGLE_RECAPTCHA_SECRET=your-secret-key

Custom Branding

HeyForm supports custom logos and brand colors through the workspace settings in the web UI. No environment variables needed — configure visually after login.

Reverse Proxy

For HTTPS, place HeyForm behind a reverse proxy. The critical detail: APP_HOMEPAGE_URL must match the public HTTPS URL exactly, or sessions will break.

# Nginx Proxy Manager: proxy to heyform:9157
# Set APP_HOMEPAGE_URL=https://forms.yourdomain.com

See Reverse Proxy Setup for full instructions.

Backup

Back up these volumes:

• heyform-mongo — all form definitions, submissions, user data
• heyform-uploads — file attachments from form responses
• heyform-keydb — session cache (less critical)

MongoDB backup:

docker exec heyform-mongo mongodump --out /tmp/backup
docker cp heyform-mongo:/tmp/backup ./heyform-mongo-backup

See Backup Strategy for a complete approach.

Troubleshooting

Login Loop (Can’t Stay Signed In)

Symptom: Login succeeds but redirects back to login page. Fix: APP_HOMEPAGE_URL doesn’t match how you’re accessing HeyForm. If you access via http://192.168.1.100:9157 but set the URL to http://localhost:9157, cookies won’t match. Update the variable to match your actual access URL.

MongoDB Connection Refused

Symptom: HeyForm fails to start with MongoDB connection error. Fix: Ensure MongoDB container is healthy: docker ps. If it’s restarting, check disk space — MongoDB needs room for journal files. Verify MONGO_URI uses the correct service name (mongo, not mongodb or localhost).

File Upload Failures

Symptom: Form file upload fields return errors. Fix: Check that the uploads volume is writable. Verify the file type is in the allowed list (UPLOAD_FILE_TYPES). Default limit is ~10 MB per file.

Resource Requirements

Resource	Minimum	Recommended
RAM	512 MB	1 GB
CPU	1 core	2 cores
Disk	2 GB (app)	5 GB+ (with uploads)

MongoDB adds ~200 MB RAM. KeyDB adds ~50 MB. Total stack: ~700 MB minimum.

Verdict

HeyForm is the best self-hosted Typeform alternative. The conversational form UX, conditional logic, and 40+ field types cover most survey and form needs. It’s lighter than LimeSurvey (which targets complex academic surveys) and more capable than simple form builders.

The main limitation is the community edition scope — some features like payment processing and advanced analytics require the enterprise version. For collecting feedback, running surveys, and building lead forms, the community edition is more than sufficient.

FAQ

How does HeyForm compare to Formbricks?

HeyForm focuses on conversational (one-question-at-a-time) forms. Formbricks focuses on in-app surveys and product research. See Formbricks vs HeyForm for a detailed comparison.

Can HeyForm accept file uploads?

Yes. File upload is a built-in field type. Configure allowed file types via the UPLOAD_FILE_TYPES environment variable. Files are stored in the uploads volume.

Does HeyForm support conditional logic?

Yes. The form editor supports conditional branching — show/hide questions or jump to specific questions based on previous answers. This is configured visually in the form builder.

Related

• Best Self-Hosted Forms & Surveys
• Formbricks vs HeyForm
• How to Self-Host Formbricks
• How to Self-Host LimeSurvey
• Self-Hosted Alternative to Typeform
• Self-Hosted Alternative to Google Forms
• Docker Compose Basics
• Reverse Proxy Setup