Streamlining Form Management with HeyForm and FerretDB
Forms are the backbone of data collection for almost every application, from simple contact forms to complex surveys and application processes. HeyForm offers a modern, open-source solution for building and managing these essential forms with ease.
At FerretDB, we're dedicated to providing a truly open-source alternative to MongoDB, leveraging the reliability and power of PostgreSQL as its backend.
In this blog post, we're excited to explore how HeyForm seamlessly integrates with FerretDB, a drop-in replacement for MongoDB, ensuring a fully open-source stack for your form management and data collection needs.
What is HeyForm?
HeyForm is an open-source form builder designed to simplify the creation, deployment, and management of online forms. It provides a user-friendly interface and powerful features, including:
- Customizable templates: Start from pre-built templates or design your own.
- Workflow automation: Integrate forms into your existing workflows.
- Data management: Collect, view, and export submission data.
- Self-hostable: Full control over your data and infrastructure.
HeyForm focuses on providing a flexible and developer-friendly platform that helps you gather information efficiently and integrate it into your applications.
Why use HeyForm with FerretDB?
HeyForm uses MongoDB as its primary database backend for storing form definitions, submissions, and user data. Given that FerretDB is designed to be a truly open source alternative to MongoDB, it can serve as a drop-in replacement for HeyForm's database. This powerful combination offers several compelling advantages:
- Open-source: Both HeyForm and FerretDB are open-source projects, providing transparency, flexibility, and strong community backing, aligning perfectly with an open-source ethos.
- Simplified infrastructure: If your existing data infrastructure is already based on PostgreSQL, integrating HeyForm with FerretDB can streamline your database management and reduce operational overhead.
- No vendor lock-in: Enjoy the freedom of truly open-source solutions without concerns about proprietary licensing or vendor lock-in.
Connecting HeyForm to FerretDB
Connecting HeyForm to your FerretDB instance is straightforward, as HeyForm uses MongoDB for primary data storage and KeyDB for caching and session management. Refer to the HeyForm self-hosting documentation for more details on its configuration options.
Here's a step-by-step guide to get you started:
-
Setup Docker Compose file: Create a
docker-compose.yml
file with the following content to define the services for HeyForm, FerretDB, and KeyDB (for caching).services:
heyform:
image: heyform/community-edition:latest
restart: always
volumes:
# Persist uploaded images
- ./assets:/app/static/upload
depends_on:
- ferretdb
- keydb
ports:
- '9513:8000'
environment:
APP_HOMEPAGE_URL: http://127.0.0.1:9513
SESSION_KEY: key1
FORM_ENCRYPTION_KEY: key2
MONGO_URI: 'mongodb://<username>:<password>@ferretdb:27017/heyform'
REDIS_HOST: keydb
REDIS_PORT: 6379
ferretdb:
image: ghcr.io/ferretdb/ferretdb-eval:2
restart: on-failure
ports:
- 27017:27017
environment:
- POSTGRES_USER=<username>
- POSTGRES_PASSWORD=<password>
- POSTGRES_DB=postgres
volumes:
# Persist FerretDB data
- ferretdb_data:/var/lib/postgresql/data
keydb:
image: eqalpha/keydb
restart: always
command: keydb-server --appendonly yes --protected-mode no
volumes:
# Persist KeyDB data
- keydb:/data
volumes:
ferretdb_data:
keydb:Replace
<username>
and<password>
with your FerretDB connection details.The above YAML file uses the latest HeyForm community edition image, FerretDB evaluation image, and KeyDB. The FerretDB evaluation image comes with FerretDB and PostgreSQL with DocumentDB extension, which is suitable for quick testing and experiments.
-
Start the services: Make sure you have Docker installed on your machine.
Then, run the following command to start all services in the
docker-compose.yml
file.docker-compose up -d
This command will pull the necessary images, create containers for HeyForm, FerretDB, and KeyDB, and start them in detached mode.
-
Access HeyForm: Once all the services are running, HeyForm should connect to FerretDB and KeyDB, initialize its database, and be accessible via its web interface. You can access it at http://127.0.0.1:9513 (or whatever port you specified in the Docker command).
You can now log into HeyForm, start building forms, and collect submissions, with all your data seamlessly stored in FerretDB.
Example of HeyForm with data in FerretDB
The below image shows a simple form created in HeyForm, demonstrating its intuitive interface and ease of use.
After setting up HeyForm and creating a new form, you can inspect how HeyForm stores its data within FerretDB.
Connect to your FerretDB instance using mongosh
by running the following command in your terminal with the appropriate username and password:
mongosh mongodb://<username>:<password>@localhost:27017/heyform
Explore the heyform
database to see the collections and documents created by HeyForm.
> show collections
appmodels
formanalyticmodels
formmodels
formreportmodels
integrationmodels
projectgroupmodels
projectmembermodels
projectmodels
submissioniplimitmodels
submissionmodels
teamactivitymodels
teaminvitationmodels
teammembermodels
teammodels
templatemodels
usermodels
usersocialaccountmodels
The form you created in HeyForm is stored in the formmodels
collection.
Query the formmodels
collection by running db.formmodels.findOne()
to see the details of the form created:
{
_id: 'zlGCuEdD',
status: 1,
draft: true,
suspended: false,
retentionAt: -1,
reversion: 0,
variables: [],
logics: [],
translations: {},
hiddenFields: [],
fields: [
{
title: [ 'Name' ],
description: [],
kind: 'short_text',
validations: { required: false },
properties: null,
id: 'uTI3y9TR6Gzp',
layout: {
mediaType: 'image',
mediaUrl: 'https://images.unsplash.com/photo-1646013532943-d5b86e8689b8?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1080&q=80',
brightness: 0,
align: 'split_right'
}
},
{
title: [ 'Email' ],
description: [],
kind: 'email',
validations: {},
properties: {},
id: 'jXWRpnXpbHXV'
},
{
title: [ 'Thank you!' ],
description: [ 'Thanks for completing this form. Now create your own form.' ],
kind: 'thank_you',
validations: null,
properties: null,
id: 'xH3vEBh0nzWM',
layout: null
}
],
kind: 1,
interactiveMode: 1,
teamId: '8f2XC8N3',
memberId: '6863fe5cde5a75001256241d',
settings: {
captchaKind: 0,
filterSpam: false,
active: false,
published: true,
allowArchive: true,
requirePassword: false,
locale: 'en',
enableQuestionList: true
},
projectId: 'HjOiBwoM',
name: 'ferretdb-form',
createdAt: ISODate('2025-07-01T19:17:43.272Z'),
updatedAt: ISODate('2025-07-01T19:50:09.958Z'),
__v: 0,
fieldUpdateAt: 1751399409
}
This output demonstrates that HeyForm successfully replaces MongoDB with FerretDB, which in turn stores its data efficiently in PostgreSQL.
Conclusion
The integration of HeyForm and FerretDB provides a robust, scalable, and fully open-source solution for building and managing online forms. By leveraging FerretDB, you can run your entire workloads in open source, without vendor lock-in or restrictive licenses.