Self-Hosting

Setup guidelines for self-hosted HeyForm.

Sponsor us

If you’re looking to self-host HeyForm, sponsoring us is a fantastic way to give back to the community and to contribute to the long-term sustainability of the project. It also comes with some perks like priority support and exclusive workshops. ❤️

One Click Deployment

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

Notice

If you want to bound your own domain to Railway or Zeabur, please replace APP_HOMEPAGE_URL with your own domain name like this below and redeploy the instance:

One Click Deployment

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
      - mongodb_data:/data/db

  keydb:
    image: eqalpha/keydb:6.3.3
    restart: always
    command: keydb-server --appendonly yes --protected-mode no
    volumes:
      # Persist KeyDB data
      - keydb:/data

volumes:
  mongodb_data:
  keydb:

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
      - mongodb_data:/data/db
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: passexample

  keydb:
    image: eqalpha/keydb:6.3.3
    restart: always
    command: keydb-server --appendonly yes --protected-mode no
    volumes:
      # Persist KeyDB data
      - keydb:/data

volumes:
  mongodb_data:
  keydb:

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
      - mongodb_data:/data/db

  keydb:
    image: eqalpha/keydb:6.3.3
    restart: always
    command: keydb-server --appendonly yes --protected-mode no
    volumes:
      # Persist KeyDB data
      - keydb:/data

volumes:
  mongodb_data:
  keydb:

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
      - mongodb_data:/data/db

  keydb:
    image: eqalpha/keydb:6.3.3
    restart: always
    command: keydb-server --appendonly yes --protected-mode no
    volumes:
      # Persist KeyDB data
      - keydb:/data

volumes:
  mongodb_data:
  keydb:
nginx.conf
# 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