Skip to content
Klutch.sh Docs

Deploying HeyForm

Introduction

HeyForm is an open-source form builder that creates engaging conversational forms for surveys, questionnaires, quizzes, and polls. Unlike traditional form builders, HeyForm presents questions one at a time in a conversational format, leading to higher completion rates and better user engagement.

Built with Node.js and React, HeyForm offers a drag-and-drop form builder with over 40 question types, logic branching, and customizable themes. The platform requires no coding skills and provides analytics to track form performance and response patterns.

Key highlights of HeyForm:

  • Conversational Interface: One question at a time for better engagement
  • 40+ Question Types: From text inputs to file uploads and payments
  • Logic Branching: Create dynamic forms based on user responses
  • Custom Themes: Brand your forms with custom colors and styles
  • Analytics Dashboard: Track completion rates and response patterns
  • Integrations: Connect with webhooks, Zapier, and other tools
  • CAPTCHA Support: Prevent spam with Google reCAPTCHA or GeeTest
  • Self-Hosted: Full control over your form data

This guide walks through deploying HeyForm on Klutch.sh using Docker, configuring the form builder, and creating your first conversational form.

Prerequisites

Before deploying HeyForm on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your HeyForm configuration
  • A MongoDB database (can be deployed separately on Klutch.sh)
  • A Redis instance for sessions (can be deployed separately)
  • (Optional) SMTP credentials for email notifications
  • Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

heyform-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official HeyForm image:

FROM heyform/community-edition:latest


# Environment variables
ENV APP_HOMEPAGE_URL=${APP_HOMEPAGE_URL}
ENV SESSION_KEY=${SESSION_KEY}
ENV FORM_ENCRYPTION_KEY=${FORM_ENCRYPTION_KEY}


# Database configuration
ENV MONGO_URI=${MONGO_URI}
ENV REDIS_HOST=${REDIS_HOST}
ENV REDIS_PORT=${REDIS_PORT:-6379}


# Expose the application port
EXPOSE 9513


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:9513/health || exit 1

Advanced Dockerfile with All Options

FROM heyform/community-edition:latest


# Application URL
ENV APP_HOMEPAGE_URL=${APP_HOMEPAGE_URL}


# Security keys
ENV SESSION_KEY=${SESSION_KEY}
ENV FORM_ENCRYPTION_KEY=${FORM_ENCRYPTION_KEY}


# MongoDB configuration
ENV MONGO_URI=${MONGO_URI}
ENV MONGO_USER=${MONGO_USER}
ENV MONGO_PASSWORD=${MONGO_PASSWORD}


# Redis configuration
ENV REDIS_HOST=${REDIS_HOST}
ENV REDIS_PORT=${REDIS_PORT:-6379}


# SMTP configuration
ENV SMTP_FROM=${SMTP_FROM}
ENV SMTP_HOST=${SMTP_HOST}
ENV SMTP_PORT=${SMTP_PORT:-587}
ENV SMTP_USER=${SMTP_USER}
ENV SMTP_PASSWORD=${SMTP_PASSWORD}


# File upload configuration
ENV UPLOAD_FILE_TYPES=${UPLOAD_FILE_TYPES:-.jpg,.png,.pdf,.doc,.docx}


EXPOSE 9513


HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:9513/health || exit 1

Environment Variables Reference

VariableRequiredDescription
APP_HOMEPAGE_URLYesPublic URL of your HeyForm instance
SESSION_KEYYesRandom string for session encryption
FORM_ENCRYPTION_KEYYesRandom string for form data encryption
MONGO_URIYesMongoDB connection string
REDIS_HOSTYesRedis server hostname
REDIS_PORTNoRedis port (default: 6379)
SMTP_FROMNoEmail sender address
SMTP_HOSTNoSMTP server hostname
SMTP_PORTNoSMTP port (default: 587)
SMTP_USERNoSMTP username
SMTP_PASSWORDNoSMTP password
UPLOAD_FILE_TYPESNoAllowed file upload extensions

Deploying HeyForm on Klutch.sh

    Deploy Prerequisites

    First, deploy MongoDB and Redis on Klutch.sh:

    • Create a MongoDB app with persistent storage
    • Create a Redis app for session management
    • Note connection details for both services

    Generate Security Keys

    Generate random strings for encryption:

    Terminal window
    openssl rand -hex 32  # For SESSION_KEY
    openssl rand -hex 32  # For FORM_ENCRYPTION_KEY

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial HeyForm deployment configuration"
    git remote add origin https://github.com/yourusername/heyform-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “heyform” or “forms”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your HeyForm repository.

    Configure HTTP Traffic

    • Select HTTP as the traffic type
    • Set the internal port to 9513

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    APP_HOMEPAGE_URLhttps://your-app-name.klutch.sh
    SESSION_KEYYour generated session key
    FORM_ENCRYPTION_KEYYour generated encryption key
    MONGO_URImongodb://your-mongo-app:27017/heyform
    REDIS_HOSTYour Redis app hostname
    REDIS_PORT6379

    Attach Persistent Volumes

    Mount PathRecommended SizePurpose
    /app/uploads20 GBFile upload storage

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start HeyForm with HTTPS enabled.

    Access HeyForm

    Once deployment completes, access your HeyForm instance at https://your-app-name.klutch.sh. Create your admin account on first access.

Using HeyForm

Creating Your First Form

  1. Log in to your HeyForm instance
  2. Click Create Form
  3. Choose a template or start from scratch
  4. Add questions using the drag-and-drop builder
  5. Configure form settings and publish

Question Types

HeyForm supports over 40 question types:

Basic:

  • Short text, Long text
  • Email, Phone number
  • Number, Date

Choice:

  • Multiple choice, Dropdown
  • Picture choice, Rating
  • Yes/No, Legal

Advanced:

  • File upload, Payment
  • Signature, Matrix
  • Calculator, Hidden fields

Logic Branching

Create dynamic forms with conditional logic:

  1. Select a question
  2. Click Logic tab
  3. Add conditions based on previous answers
  4. Set jump destinations for each condition

Form Settings

Configure your form behavior:

  • Welcome/Thank You screens: Customize messages
  • Progress bar: Show completion progress
  • Keyboard shortcuts: Enable for power users
  • Submission limits: Set maximum responses
  • Scheduling: Set start and end dates

Collecting Responses

View and manage responses:

  1. Navigate to your form
  2. Click Responses tab
  3. View individual responses or summary
  4. Export to CSV or Excel

Integrations

Webhooks

Send form data to external services:

  1. Go to form settings
  2. Click Integrations
  3. Add webhook URL
  4. Configure payload format

CAPTCHA

Prevent spam submissions:

  1. Go to Settings > Security
  2. Enable Google reCAPTCHA or GeeTest
  3. Enter your API credentials
  4. CAPTCHA appears on forms automatically

Troubleshooting

Form Not Loading

  • Verify MongoDB and Redis are running
  • Check environment variables are correct
  • Review application logs for errors

File Upload Fails

  • Check allowed file types configuration
  • Verify upload directory permissions
  • Ensure sufficient storage space

Email Notifications Not Sending

  • Verify SMTP configuration
  • Check SMTP credentials are correct
  • Review mail logs for errors

Additional Resources

Conclusion

Deploying HeyForm on Klutch.sh provides a powerful, self-hosted form builder with conversational interfaces that boost completion rates. The drag-and-drop builder, logic branching, and extensive question types make it easy to create engaging surveys and questionnaires. With full control over your data and extensive customization options, HeyForm on Klutch.sh is an excellent choice for organizations needing a privacy-focused form solution.