Deploy HeyForm | (Just Updated) Typeform Alternative, Form Builder With Admin Login Generated, Sign-Up Closed
HeyForm self-hosted form builder, Typeform alternative, MongoDB and Redis
mongo
Just deployed
/data/db
redis
Just deployed
/data
heyform
Just deployed
/app/packages/server/static/upload
Deploy and Host HeyForm on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the admin login, the session and encryption keys and the database and Redis passwords are generated, the server cannot start without them, and the admin account exists before the first request. HeyForm is a self-hosted conversational form and survey builder, an open-source alternative to Typeform and Google Forms for collecting submissions on your own domain.
About Hosting HeyForm
This template runs three services: heyform, the upstream HeyForm community-edition image (v3.0.7) pinned by digest through a thin wrapper, mongo, a MongoDB 8.0 database with a volume at /data/db that holds forms, submissions and accounts, and redis, a Redis 8 instance with a volume at /data that holds sessions and rate limits. The heyform service has a volume at /app/packages/server/static/upload for uploaded files. One public domain serves the app and its GraphQL API. The server listens on Railway's injected PORT, and the healthcheck is GET /health.
What the wrapper fixes. Upstream gives a self-hosted deployer no way to create the first account once registration is closed, and every setting (database, Redis, session and encryption keys) is a variable to type. The wrapper bakes the fixed settings into the image so the deploy form is empty, closes public registration, refuses to start without a strong admin password and three keys of at least 24 characters, and creates the admin account at boot with an idempotent database insert from ADMIN_EMAIL and ADMIN_PASSWORD (a restart leaves an existing account unchanged). Read from the upstream source and checked on a Railway deploy: sign-up answers Registration is disabled, the generated login signs in. Not reproduced on a Railway control of an incumbent listing.
Using it. Open the domain and sign in with ADMIN_EMAIL and ADMIN_PASSWORD. Create a workspace and a form; everything is stored in MongoDB, so redeploys keep it.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of theheyformservice) - Private URL:
http://heyform.railway.internal:8080 - Credentials: the variables
ADMIN_EMAILandADMIN_PASSWORDon theheyformservice (plain text;ADMIN_EMAILisadmin@plus the public domain) - Auth: GraphQL at
POST /graphqlwithContent-Type: application/jsonand anx-device-idheader of your choosing on every call.query{login(input:{email,password})}returnstrueand sets theHEYFORM_SESSIONcookie; send that cookie back on later calls. HeyForm answers HTTP 200 for a refused call and puts the refusal in the body (UNAUTHORIZED,Registration is disabled). - Health:
GET /healthreturns 200 without credentials;GET /health/readyreports"mongo":"up","redis":"up"
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, ADMIN_EMAIL, ADMIN_PASSWORD (variables of the heyform service); also curl, grep, sed.
R="https://$RAILWAY_PUBLIC_DOMAIN"; D="x-device-id: agent-$$"; J="content-type: application/json"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/health")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/health"
# HeyForm is a GraphQL API at POST /graphql. Every call carries an x-device-id header; the session is the HEYFORM_SESSION cookie that login sets.
gql() { curl -s -H "$J" -H "$D" "$@" "$R/graphql"; }
echo "health ready: $(curl -s "$R/health/ready" | grep -o '"mongo":"[a-z]*","redis":"[a-z]*"')"
# a wrong password does not sign in
echo "wrong password: $(gql -d '{"query":"query($i:LoginInput!){login(input:$i)}","variables":{"i":{"email":"'"$ADMIN_EMAIL"'","password":"not-the-admin-secret"}}}' | grep -o 'Incorrect email or password')"
# the generated login signs in and sets the session cookie
S=$(curl -s -i -H "$J" -H "$D" -d '{"query":"query($i:LoginInput!){login(input:$i)}","variables":{"i":{"email":"'"$ADMIN_EMAIL"'","password":"'"$ADMIN_PASSWORD"'"}}}' "$R/graphql" | grep -i '^set-cookie: HEYFORM_SESSION=' | sed 's/^[^:]*: //;s/;.*//')
echo "login: $(echo "$S" | cut -c1-15)"
echo "signed in as: $(gql -H "cookie: $S" -d '{"query":"query{userDetail{email}}"}' | grep -o '"email":"[^"]*"')"
# write-auth: a write (create a workspace) with the session succeeds, the same write without it is refused
echo "write with session: $(gql -H "cookie: $S" -d '{"query":"mutation{createTeam(input:{name:\"Agent\",projectName:\"First\"})}"}' | grep -o '"createTeam":"[A-Za-z0-9]*"' | sed 's/:.*/ created/')"
echo "write without key: $(curl -s -H "$J" -H "$D" -d '{"query":"mutation{createTeam(input:{name:\"Anon\",projectName:\"First\"})}"}' "$R/graphql" | grep -o 'UNAUTHORIZED')"
# signup: HeyForm answers HTTP 200 for a refused GraphQL call, so the refusal is read from the body
echo "public signup: $(curl -s -H "$J" -H "$D" -d '{"query":"mutation($i:SignUpInput!){signUp(input:$i)}","variables":{"i":{"email":"stranger@example.org","name":"Stranger","password":"Stranger-0123456789"}}}' "$R/graphql" | grep -o 'Registration is disabled')"
Expected output against a fresh deploy (measured on the Railway demo and on a control deploy of the published code; the output is recorded in template.md):
health: 200
health ready: "mongo":"up","redis":"up"
wrong password: Incorrect email or password
login: HEYFORM_SESSION
signed in as: "email":"admin@heyform-production-example.up.railway.app"
write with session: "createTeam" created
write without key: UNAUTHORIZED
public signup: Registration is disabled
The refusals are the contract: a wrong password answers Incorrect email or password, a write without the session answers UNAUTHORIZED (write without key: UNAUTHORIZED, HTTP 200 with the refusal in the body), and a stranger's sign-up answers Registration is disabled (public signup: Registration is disabled).
Why Deploy HeyForm on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying HeyForm on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
- Agent-ready - no deployer fields, a contract block, and one script that proves the server is healthy, a wrong password and a stranger do not get in, and the generated login does.
- Locked from the first request - registration is closed, the admin account is created at boot, and the server will not start without strong secrets.
- Data survives redeploys - forms and submissions live in MongoDB on a volume, sessions in Redis on a volume, uploads on a volume.
- Works on first deploy - the listener follows Railway's injected
PORTand the databases are reached over the private network. - Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.
Common Use Cases
- Surveys and lead forms on your own domain - collect responses without sending them to a third-party form service.
- A Typeform replacement - one-question-at-a-time forms with logic, hidden fields and file uploads.
- Feedback and signup forms for a product - embed forms in a site and read submissions through the dashboard.
Dependencies for HeyForm Hosting
- The heyform service, a MongoDB service and a Redis service, each with its volume, created by the template.
Deployment Dependencies
Template Content
