Deploy HeyForm

Deploy and Host HeyForm on Railway

HeyForm is an open-source form builder for conversational forms, surveys, quizzes and polls. It asks one question at a time, supports twenty-plus field types from short text and ratings to file uploads, signatures and payments, and adds conditional logic, redirects, themes and custom CSS. Teams reach for it when Typeform's per-response pricing stops adding up, or when submissions hold data that has to stay on their own infrastructure.

Self-host HeyForm on Railway and this template wires the stack together: heyform serves the dashboard and the public form renderer on one domain, MongoDB stores workspaces, forms and submissions, Redis backs the job queues, and mailpit captures outgoing mail so verification, password resets and invitations work the moment the deploy finishes. Respondents reach heyform over HTTPS; MongoDB, Redis and Mailpit's SMTP listener stay private.

Getting Started with HeyForm on Railway

Open the heyform service's public URL and you land on the sign-up page — there is no default account, and the first person to register owns their workspace. Enter a name, email and password, and the app emails a six-digit code; until you enter it, every dashboard route redirects back to the verification screen. Open the mailpit service's URL in a second tab, sign in with the credentials in its MP_UI_AUTH variable, read the code, enter it, then name your workspace.

From the dashboard, click Create Form, choose Start from scratch, type your first question onto the canvas and use the + beside Questions to add more — rating, choice, file upload, date, payment. Hit Publish for a share link at https://your-domain/form/, open it in a private window and submit a test response: it appears within seconds under Submissions, with completion rate under Analytics. Then set APP_DISABLE_REGISTRATION to true so strangers cannot sign up; invitation-link holders still can.

About Hosting HeyForm

HeyForm is built by EarlyBird, Inc. and released under AGPL-3.0. The community edition is the same product as the hosted service, with no response caps, seat limits or withheld features — the difference is that you run it. That matters most when a form collects personal data and "who holds the responses" has a compliance answer.

Key capabilities:

• One-question-at-a-time conversational forms, plus classic multi-question layouts
• Twenty-plus question types, including file upload, signature, payment and opinion scale
• Conditional logic, variables, hidden fields and completion redirects
• Themes, custom fonts, background images and per-form CSS
• Drop-off analytics and CSV export of responses
• Webhooks plus Zapier, Make.com, Slack, Sheets and Airtable integrations
• Optional Google, Apple and OpenID Connect sign-in

The topology mirrors the project's own Compose file. heyform is a single Node process serving the dashboard, the form renderer and the GraphQL API, so there is no separate frontend to keep in sync. MongoDB is the only database. Redis carries the Bull queues that send mail and build reports, and holds rate-limit and verification-code state. mailpit is capture-only SMTP with a web inbox; point it at a real relay later, or give heyform your own provider's SMTP_* values.

Why Deploy HeyForm on Railway

Railway removes the setup work between a Docker image and a live form endpoint.

• MongoDB, Redis and SMTP provisioned and wired on the first deploy
• Public HTTPS domain and certificate, no reverse proxy to configure
• A persistent volume keeps uploaded files across redeploys
• Private networking keeps the database and mail server off the internet
• Health checks watch MongoDB and Redis, not just the container

Common Use Cases

• Customer feedback and NPS surveys whose responses stay in your database
• Job applications and lead capture with file uploads landing on your own volume
• Internal request forms — tickets, expense claims, sign-ups — where conditional logic lets one form cover several paths
• Product research and quizzes embedded with the standard, modal, popup or full-page snippet

Dependencies for HeyForm

• heyform/community-edition:latest — the application image, from github.com/heyform/heyform
• mongo:8.0 — document database for every workspace, form and submission
• redis:8.2 — queues and cache behind the Bull workers and rate limiters
• axllent/mailpit:latest — SMTP capture server and inbox for verification mail

Environment Variables Reference

Deployment Dependencies

• Source: github.com/heyform/heyform
• Image: hub.docker.com/r/heyform/community-edition
• Docs: docs.heyform.net
• Runtime: Node.js 22 on Alpine, MongoDB 8, Redis 8

Hardware Requirements for Self-Hosting HeyForm

Self-Hosting HeyForm with Docker

The image is multi-architecture, so one container plus MongoDB and Redis runs it anywhere. A minimal command, assuming both are reachable:

docker run -d --name heyform -p 9157:9157 \
  -e APP_HOMEPAGE_URL=https://forms.example.com \
  -e SESSION_KEY=change-me -e FORM_ENCRYPTION_KEY=change-me-too \
  -e MONGO_URI=mongodb://mongo:27017/heyform \
  -e REDIS_HOST=redis -e REDIS_PORT=6379 \
  -e SMTP_HOST=smtp.example.com -e SMTP_PORT=587 \
  -v heyform_uploads:/app/packages/server/static/upload \
  heyform/community-edition:latest

To build from source, clone the repository and use the Dockerfile at its root:

git clone https://github.com/heyform/heyform.git
cd heyform && docker build -t heyform:local .

Keep SESSION_KEY and FORM_ENCRYPTION_KEY stable forever: regenerating them invalidates every session and every protected form link already shared.

How Much Does HeyForm Cost to Self-Host?

The community edition is free and open source under AGPL-3.0, with no response limits, member limits or paywalled fields. The hosted plans run from $15 a month for 5,000 responses to $40 for 150,000, so self-hosting swaps a subscription for infrastructure cost alone. On Railway you pay for the four services' compute plus database and upload storage, which tracks traffic rather than responses.

FAQ

What is HeyForm?

An open-source form and survey builder that asks questions one at a time, in the style of Typeform. It covers form design, conditional logic, themes, analytics and CSV export, under AGPL-3.0.

What does this Railway template deploy?

Four services: HeyForm on a public domain with a volume for uploads, MongoDB for application data, Redis for the job queues, and Mailpit as an SMTP server with a web inbox.

Why does the template include Redis and MongoDB?

MongoDB is HeyForm's only datastore — forms, submissions, users and workspaces all live there. Redis is not optional either: mail, reporting and translation run through Bull queues, and rate limits and single-use verification codes live there.

Do I need to configure SMTP to use self-hosted HeyForm?

Yes, which is why Mailpit ships with this template. A new account is held on the verification screen until it enters a code sent by email, so an instance with no working SMTP host never reaches its dashboard. Swap the SMTP_* variables for a real provider before going live.

Where are uploaded files stored in self-hosted HeyForm?

On the volume at /app/packages/server/static/upload, served back at /static/upload/. For object storage, set S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY — the bucket must allow anonymous reads, since respondents get the object URL directly.

Can I use my own domain and single sign-on?

Yes. Attach a custom domain, update APP_HOMEPAGE_URL to match and redeploy. For SSO set OIDC_ISSUER, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET for any OpenID Connect provider, and register /connect/oidc/callback with it.