Self-Hosting

Setup guidelines for self-hosted HeyForm.

One Click Deployment

Easy to deploy with one click and come with free credits.

Deploy with Docker

Requirements

Before you begin, ensure you have the following:

  • Basic knowledge of Docker and containerization principles.
  • Docker and Docker Compose are installed on your machine.

Configuration

Using this sample file as a reference create a docker.env file or environment in docker-compose.yml to contain the environment variables for your installation.

Docker Compose

1. Install Docker and Docker Compose:

For macOS users, you can install them by Homebrew:

brew install docker docker-compose

For Windows users, you can install them by Chocolatey:

choco install docker-desktop docker-compose -y

2. Create a docker-compose.yml file, an example configuration with all dependencies dockerized and environment variables is as follows:

Here are four different use cases. Please refer to their APP_HOMEPAGE_URL settings. Incorrect settings may result in login issues.

Run on your own computer
docker-compose.yml 
networks:
  keydb:
  mongo:

services:
  heyform:
    image: heyform/community-edition:latest
    restart: always
    volumes:
      # Persist uploaded images
      - ./assets:/app/static/upload
    depends_on:
      - mongo
      - keydb
    ports:
      - '9513:8000'
    environment:
      APP_HOMEPAGE_URL: http://127.0.0.1:9513
      SESSION_KEY: key1
      FORM_ENCRYPTION_KEY: key2
      MONGO_URI: 'mongodb://mongo:27017/heyform'
      REDIS_HOST: keydb
      REDIS_PORT: 6379

  mongo:
    image: percona/percona-server-mongodb:4.4
    restart: always
    volumes:
      # Persist MongoDB data
      - ./database:/data/db

  keydb:
    image: eqalpha/keydb:latest
    restart: always
    command: keydb-server --appendonly yes
    volumes:
      # Persist KeyDB data
      - ./keydb:/data

Connect MongoDB with username and password
docker-compose.yml 
networks:
  keydb:
  mongo:

services:
  heyform:
    image: heyform/community-edition:latest
    restart: always
    volumes:
      # Persist uploaded images
      - ./assets:/app/static/upload
    depends_on:
      - mongo
      - keydb
    ports:
      - '9513:8000'
    environment:
      APP_HOMEPAGE_URL: http://127.0.0.1:9513
      SESSION_KEY: key1
      FORM_ENCRYPTION_KEY: key2
      MONGO_URI: 'mongodb://mongo:27017/heyform?authSource=admin'
      MONGO_USER: root
      MONGO_PASSWORD: passexample
      REDIS_HOST: keydb
      REDIS_PORT: 6379

  mongo:
    image: percona/percona-server-mongodb:4.4
    restart: always
    volumes:
      # Persist MongoDB data
      - ./database:/data/db
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: passexample

  keydb:
    image: eqalpha/keydb:latest
    restart: always
    command: keydb-server --appendonly yes
    volumes:
      # Persist KeyDB data
      - ./keydb:/data

Allow other computers in the local network to access
docker-compose.yml 
version: '3'

services:
  heyform:
    image: heyform/community-edition:latest
    restart: always
    volumes:
      # Persist uploaded images
      - ./assets:/app/static/upload
    depends_on:
      - mongo
      - keydb
    ports:
      - '9513:8000'
    environment:
      APP_HOMEPAGE_URL: http://192.168.1.50:9513
      SESSION_KEY: key1
      FORM_ENCRYPTION_KEY: key2
      MONGO_URI: 'mongodb://mongo:27017/heyform'
      REDIS_HOST: keydb
      REDIS_PORT: 6379

  mongo:
    image: percona/percona-server-mongodb:4.4
    restart: always
    volumes:
      # Persist MongoDB data
      - ./database:/data/db

  keydb:
    image: eqalpha/keydb:latest
    restart: always
    command: keydb-server --appendonly yes
    volumes:
      # Persist KeyDB data
      - ./keydb:/data

Deploy to a public server
docker-compose.yml 
networks:
  keydb:
  mongo:

services:
  heyform:
    image: heyform/community-edition:latest
    restart: always
    volumes:
      # Persist uploaded images
      - ./assets:/app/static/upload
    depends_on:
      - mongo
      - keydb
    ports:
      - '9513:8000'
    environment:
      APP_HOMEPAGE_URL: http://form.yourcompany.com
      SESSION_KEY: key1
      FORM_ENCRYPTION_KEY: key2
      MONGO_URI: 'mongodb://mongo:27017/heyform'
      REDIS_HOST: keydb
      REDIS_PORT: 6379

  mongo:
    image: percona/percona-server-mongodb:4.4
    restart: always
    volumes:
      # Persist MongoDB data
      - ./database:/data/db

  keydb:
    image: eqalpha/keydb:latest
    restart: always
    command: keydb-server --appendonly yes
    volumes:
      # Persist KeyDB data
      - ./keydb:/data
docker-compose.yml 
# Nginx config
# To deploy to a public server, you will also need to configure nginx for reverse proxying the NodeJs program

server {
  listen 80;
  server_name form.yourcompany.com;

  location / {
    proxy_pass http://heyform:9513;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
  }
}

Run it

Make sure you are in the same directory as docker-compose.yml and start HeyForm:

docker-compose up -d

When you run this command, by default, it does the following:

  • Create a database
  • Run the migrations
  • Start the HeyForm web app on port 9513

You can now navigate to http://<server ip>:9513 or http://form.yourcompany.com and see the login screen. HeyForm itself does not perform SSL termination. It only runs on unencrypted HTTP. If you want to run on HTTPS you also need to set up a reverse proxy in front of the server.

Connect with Stripe
Local development