---
title: "Deploy HeyForm"
description: "Form builder for surveys, quizzes and polls, one question at a time"
category: "Other"
url: https://railway.com/deploy/heyform
---

# Deploy HeyForm

Form builder for surveys, quizzes and polls, one question at a time

**[Deploy HeyForm on Railway](https://railway.com/template/heyform)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/heyform/manifest.json

- **Creator:** A3A
- **Category:** Other
- **Total deploys:** 1

## Template content

### MongoDB https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mongodb.svg

- **Image:** mongo:8.0
- **Start command:** `docker-entrypoint.sh mongod --ipv6 --bind_ip ::,0.0.0.0 --setParameter diagnosticDataCollectionEnabled=false`

### mailpit https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mailpit.svg

- **Image:** axllent/mailpit:latest
- **Health check:** /livez
- **Public domain:** Yes

### Redis https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/redis.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### heyform https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/heyform.svg

- **Image:** heyform/community-edition:latest
- **Health check:** /health/ready
- **Public domain:** Yes

## Documentation

# 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.

![Diagram of the HeyForm, Mailpit, MongoDB and Redis services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1789005662/heyform-architecture.png)

## 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.

![HeyForm workspace overview listing a published feedback form](https://res.cloudinary.com/rroe4rtk/image/upload/v1789005664/heyform-workspace-dashboard.png)
![Editing a question in the HeyForm form builder](https://res.cloudinary.com/rroe4rtk/image/upload/v1789005666/heyform-form-builder.png)
![HeyForm analytics report with responses and a rating breakdown](https://res.cloudinary.com/rroe4rtk/image/upload/v1789005668/heyform-analytics-report.png)

## 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](https://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

| Variable | Purpose |
|---|---|
| `APP_HOMEPAGE_URL` | Public base URL; sets the cookie domain and upload origin |
| `PORT` / `APP_LISTEN_PORT` | `9157` — probed port and bound port |
| `SESSION_KEY` / `FORM_ENCRYPTION_KEY` | Encrypt sessions, form tokens and protected links |
| `MONGO_URI` | Connection string, with database name and `authSource=admin` |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis connection; queues use `REDIS_DB + 1` |
| `SMTP_HOST` / `SMTP_PORT` / `SMTP_FROM` | Outbound mail; without it nobody can verify |
| `TRUST_PROXY` | `true` behind Railway's edge, so limits key on the real client IP |
| `APP_DISABLE_REGISTRATION` | `true` closes public sign-up after your account exists |
| `S3_ENDPOINT` and friends | Optional external storage; unset serves from the volume |

### Deployment Dependencies

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

## Hardware Requirements for Self-Hosting HeyForm

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2 vCPU |
| RAM | 1 GB app, 512 MB MongoDB | 2 GB app, 1 GB MongoDB |
| Storage | 1 GB upload volume | 5 GB or more if forms accept files |
| Runtime | Node.js 22, MongoDB 4.4+, Redis 6+ | Node.js 22, MongoDB 8, Redis 8 |

## 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.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/heyform