A super light-weight node.js version of Enketo Smart Paper. Chock-full of badass rockstar tech.

1. Install JS prerequisites: Node.js 0.10.x (not 0.11), Grunt Client, and Bower
2. Install Redis
3. Install libxslt and libxml2 with (sudo) apt-get install libxml2-dev libxslt1-dev
4. Clone this repository
5. Clone git submodules with git submodule update --init --recursive
6. install dependencies with npm install and bower install from the project root
7. Build with grunt from the project root

1. Install Vagrant and VirtualBox
2. Clone this repository
3. Run vagrant up from the enketo-express folder and wait until it completes *
4. The app should now be running on http:https://localhost:8006 (to stop: run pm2 stop enketo from VM)

* sometimes vagrant up fails for reasons beyond our control - e.g. if external resources are temporarily unavailable. Try running vagrant reload --provision to resolve this.

All configuration is done in config.json. The configuration items have self-explanatory names and helpful sample values. After editing the configuration, the app will need to be restarted.

The maps configuration can include an array of Mapbox TileJSON objects (or a subset of these with at least a tiles (array) and an attribution property)

The default production configuration includes 2 redis instances for the cache. You can greatly simplify installation by using 1 redis instance instead (for non-production usage). To do this set the redis.cache.port to 6379 (same as redis.main.port). To set up 2 instances properly for production, you'll find the vagrant setup steps in bootstrap.sh useful.

To configure external authentication see this section.

The API is accessible on /api/v2 (v2 is backwards-compatible with enketo-legacy's v1).

Run with npm start from project root.

You can now check that the app is running by going to e.g. http:https://localhost:8005 (depending on your server and port set in config.json or the port forwarding set up in Vagrant (default is 8006))

For a production server, we recommend using pm2 to manage the node app.

• update git repository with git pull && git submodule update --init --recursive
• update dependencies with npm update && bower update
• re-build with grunt

Install nodemon to automatically restart the server when a file changes. Install gulp to automatically update the translation keys.

The easiest way to start the app in development and debugging mode with livereload is with grunt develop. If you are developing using the vagrant VM, make sure to pm2 kill first or comment out the pm2 block at the end in the bootstrap script before creating the VM.

• ✅ this one is 100% JavaScript
• ✅ this one is much easier to install
• ✅ this one can be hosted on a local webserver
• ✅ this one has a multi-language user interface
• ✅ this one has cross-browser (media) file inputs
• ✅ this one has better security of user credentials
• ✅ this one has an improved API (v2)
• ✅ this one has support for multiple themes in all form views including previews
• ✅ this one allows overriding a form-defined theme via the API (v2)
• ✅ this one has the ability to override default form values on launch through the API (v2)
• ✅ this one has a more advanced iframeable webform view that can communicate back to the parent window, enabled through the API (v2)
• ✅ this one has external authentication support
• ✅ this one will use the instanceName value defined in the XForm as the default local record name
• 🔶 offline forms are still experimental - enable offline functionality only for testing and report bugs please
• ❌ missing API endpoints and corresponding views: all endpoints containing "/single" (single submission views), and "/surveys/list"
• ❌ no export of queued records (yet)
• ❌ no Formtester app (planning to integrate this functionality in the form previews)
• ❌ no Forms app (you do not need this)

The default theme can be set in config.json. The default theme can be overridden in the form definition.

The recommended way to customize themes is to either:

• Send a pull request for changes to the existing themes, or
• Contact Enketo LLC for a quote to make changes to existing themes or to create a new theme, or
• Create your own theme in your own enketo-express port and add your custom theme in its own folder here. No other changes are required. A succesful rebuild with grunt, and your theme will become active when the app starts. The advantage of using this method instead of editing the existing themes, is that you will not have any merge conflicts when you update your port! Add a print-specific version of your theme and use the same filenaming convention as the built-in themes.

This app does not (yet) manage OpenRosa form authentication for protected forms, i.e. it does not provide a login page, does not store credentials and does not manage any authenticated sessions.

It does enable the use of external authentication, i.e. the authentication management of your form and data server. Whenever a request (form, formlist, submission) requires authentication, enketo-express re-directs the user to a login page on the form and data server and simply passes any cookies back to that server whenever it makes any subsequent request. It is up to the form and data server to authenticate based on the cookie content. This mechanism requires any enketo-express webform to have access to these browser cookies so the form/data server and Enketo Express would have to be on the same domain (a different subdomain is possible when setting cross-domain cookies). It also requires the login page to have a mechanism for redirecting the authenticated user back, via a query string parameter.

To make use of external authentication set the following in config.json:

• linked form and data server -> authentication -> managed by enketo -> false
• linked form and data server -> authentication -> external login url that sets cookie -> e.g. http:https://example.com/login?return={RETURNURL}, where {RETURNURL} will be set by enketo.

There are two potential security issues to be aware of, both of should be resolved by running this application on https with a valid SSL certificate.

API security is mainly arranged by the secret API key set up in config.json. This API key is sent in cleartext to Enketo by the form/data server (such as ODK Aggregate) and can easily be intercepted and read if the transport is not secure. Somebody could start using your Enketo Express installation for their own form/data server, or obtain the URLs of your forms. Using secure (https) transport mitigates against this hazard. Security increases as well by populating the server url in config.json. Also, don't forget to change your API key when you start running Enketo Express in production.

Form authentication is only secure when Enketo is running on https. To avoid leaking form server credentials, authentication is automatically disabled when the app is accessed in a 'production' environment on 'http'. If you have to to run the app on http in a production environment, you can bypass this security by setting "allow insecure transport": true in config/config.json. The only use case this would be acceptable in is when running the app on a local protected network (e.g. in the KoBo VM).

The user interface was translated by: Martijn van de Rijdt (Dutch), ...

Send a message if you'd like to contribute! We use an easy web interface provided by Transifex.

The development of this application was funded by KoBo Toolbox (Harvard Humanitarian Initiative), iMMAP, OpenClinica, and Enketo LLC. The Enketo-core library (the form engine + themes) used in this application obtained significant funding from SEL (Columbia University), the Santa Fe Institute, and the HRP project.

See the license document for this application's license.

Note that some of the libraries used in this app have different licenses.

The Enketo logo and Icons are trademarked by Enketo LLC. They can be used in the KoBoCAT VM only. If you are using this app to build your own web application, you are encouraged to maintain the 'powered by Enketo' form footer with the Enketo logo, but replace other images in /public/images with your own or contact Enketo LLC to discuss the use inside your app.

See CHANGELOG