Skip to content
forked from tellform/tellform

✏️ Free Opensource Alternative to TypeForm or Google Forms


Notifications You must be signed in to change notification settings



Repository files navigation

TellForm 2.1.0

Build Status Project Status Codacy Badge Gitter

An opensource alternative to TypeForm that can create stunning mobile-ready forms , surveys and questionnaires.


Table of Contents


Currently following features are implemented:

  • Multi-Language Support
  • 11 possible question types
  • Editable start and end pages
  • Export Submissions to XLS, JSON or CSV
  • Native Analytics and Google Analytics Support
  • Custom Subdomains for each User
  • Embeddable Forms
  • Forms as a Service API
  • Deployable with Heroku and DockerHub

On the Roadmap for v3.0.0

  • Implement encryption for all form data
  • Add Typeform API integration
  • Add plugin/3rd party integration support (ala Slack)
  • Create wiki for easy installation and setup
  • Add Stripe/Payment Form field
  • Add Custom Background and Dropdown Field Images
  • Add File Upload Form Field

How to Contribute

Please checkout our on ways to contribute to TellForm.

All contributors are eligible to get a free TellForm Sticker. All you have to do is submit a PR, get it accepted, email your address to team [at] and we'll send you a sticker that you can proudly put on your laptop.


Before you start, make sure you have

  1. Redis installed and running at
  2. MongoDB installed and running at (OR specify the host and port in config/env/all)

Also make sure to install DNS Masq or equivalent if running it locally on your computer (look at dns_masq_setup_osx for instructions on OSX)

Install dependencies first.

$ npm install
$ bower install

Setup environment.

$ grunt build

Create your user account

$ node ./scripts/setup.js

OR create your .env file


# Mail config

# Use this for one of Nodemailer's pre-configured service providers

# Use these for a custom service provider

Side note: Currently we are using Raven and Sentry for error logging. To use it you must provide a valid private DSN key in your .env file and a public DSN key in app/views/layout.index.html

To run the development version:

Set NODE_ENV=development in .env file $ grunt

To run the production version:

Set NODE_ENV=production in .env file $ grunt

Your application should run on port 3000 or the port you specified in your .env file, so in your browser just go to http://localhost:3000

Deploying with Docker

To deploy with docker, first install docker here.

Then see this page here for commands on how to deploy your own local TellForm instance.

Testing Your Application

You can run the full test suite included with TellForm with the test task:

$ grunt test

This will run both the server-side tests (located in the app/tests/ directory) and the client-side tests (located in the public/modules/*/tests/).

To execute only the server tests, run the test:server task:

$ grunt test:server

And to run only the client tests, run the test:client task:

$ grunt test:client

Currently the live example uses heroku github deployments. The Docker file is out of date and does not work. If someone wishes to get it working feel free to submit a pull request.

To calculate your total test coverage with Istanbul, run the coverage task

$ grunt coverage

To calculate your server-side test coverage with Istanbul, run the coverage task

$ grunt coverage:server

To calculate your client-side test coverage with Istanbul, run the coverage task

$ grunt coverage:client


TellForm's configuration is done with environment variables. To set an option for TellForm, open/create your .env file and set add ENV_VAR=somevalue to set the ENV_VAR variable to the value somevalue.

Property Valid Values Default Value Description Required?
NODE_ENV "development", "production", "test" or "secure" development Set which version of the app you want to run (either secure/SSL, dev, prod or test) No
SESSION_SECRET Any string CHANGE_ME_PLEASE Value used to compute session hash No
BASE_URL A valid URL localhost:3000 URL where the admin panel will live Yes
MONGODB_URI A valid MongoDB URI localhost/mean URI of the MONGODB server/db that your server will use Yes
REDIS_URL A valid Redis URI redis:// URI of the Redis instance that your server will use Only if ENABLE_CLUSTER_MODE=TRUE
SOCKET_PORT A valid port number from 0 - 65535 20523 Port that your SocketIO server will bind to No
SOCKET_URL A valid URL Url that your SocketIO server will bind to No
SIGNUP_DISABLED "TRUE" or "FALSE" FALSE Set this flag to disable signups. No
SUBDOMAINS_DISABLED "TRUE" or "FALSE" FALSE Set this flag to disable subdomains. (Useful if hosting behind an uncontrolled domain or without a wildcard SSL cert) No
ENABLE_CLUSTER_MODE "TRUE" or "FALSE" FALSE Disable support for running TellForm with pm2's cluster mode. Disabling this allows you to not run a Redis instance. No
MAILER_EMAIL_ID A string N/A Username credential for the SMTP MAIL service used to send signup/verification/lost password emails. Yes
MAILER_PASSWORD A string Password credential for the SMTP MAIL service used to send signup/verification/lost password emails. Yes
MAILER_FROM A valid email Email address that all mail should be sent from. No
MAILER_SERVICE_PROVIDER A service from A "well-known" email service that is supported by nodemail. If MAILER_SMTP_HOST is enabled, this is ignored. Only if MAILER_SMTP_HOST is not set
MAILER_SMTP_HOST A valid URL URL to the SMTP server of your choice Only if MAILER_SERVICE_PROVIDER is not set
MAILER_SMTP_PORT A valid port number from 0 - 65535 Port of the SMTP server of your choice. Only if MAILER_SMTP_HOST is set
MAILER_SMTP_SECURE "TRUE" or "FALSE" FALSE Boolean that enables/disables SSL support for your SMTP client. Only if MAILER_SMTP_HOST is set
CREATE_ADMIN "TRUE" or "FALSE" FALSE Setting this variable will create a admin user on startup with credentials as specified below No
ADMIN_EMAIL A valid email Email of generated admin user No
ADMIN_USERNAME A string root Username of generated admin user No
ADMIN_PASSWORD A string root Password of generated admin user No
APP_NAME A string TellForm Sets the <title> property of your webapp. No
APP_DESC A string Opensource form builder alternative to TypeForm Sets the,property of your webapp. No
APP_KEYWORDS A comma-seperated list of phrases/words typeform, pdfs, forms, opensource, formbuilder, google forms, nodejs Sets the value of the description attribute. No
RAVEN_DSN A valid DSN N/A Set this to your Public DSN to enable remote logging No
GOOGLE_ANALYTICS_ID A valid Google Analytics ID N/A Set this to your GA id to enable GA tracking on your TellForm instance No

Where to get help

Gitter Chat

Official Twitter


Does your company use TellForm? Help keep the project bug-free and feature rich by sponsoring the project.


Love our work and community? Become a backer.


David Baldwynn

💻 🔧 🚇 📖 💡 🎨 🔍 👀 ⚠️

Samuel Laulhau

💻 🌍

Arun Pattnaik


Thiên Toán

🐛 💻 📖

Adrian Portabales

🐛 💻

Peter Thaleikis


Mickaël Andrieu


Ahmad Luqman


Peter Dave Hello


Mentions on the Web

Mister Ad

BootCSS Expo

Product Hunt

Hacker News Post

Reddit Posts



✏️ Free Opensource Alternative to TypeForm or Google Forms



Code of conduct





No packages published


  • JavaScript 68.8%
  • HTML 23.0%
  • CSS 7.6%
  • Other 0.6%