Skip to content

Latest commit

 

History

History
155 lines (83 loc) · 11.2 KB

README.md

File metadata and controls

155 lines (83 loc) · 11.2 KB
Raw

Enketo Express Build Status Dependency Status Codacy Badge

Enketo Logo

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

How to install a test/development server

Manually:

  1. Install JS prerequisites: Node.js (4.x LTS recommended), Grunt Client, and Node-Gyp
  2. Install Redis
  3. Install build-essential and git (and libfontconfig to run tests) with (sudo) apt-get install build-essential git libfontconfig
  4. Clone this repository
  5. Install dependencies with npm install from the project root
  6. Create config/config.json to override values in the default config. Start with cp config/default-config.json config/config.json
  7. Build with grunt from the project root

Using vagrant:

This takes several shortcuts. Do not use for production!

  1. Install Vagrant and VirtualBox
  2. Run vagrant up from project folder and wait until it completes *
  3. Log in to the VM with vagrant ssh and run cd /vagrant && npm start

The app should now be running on localhost:8006. You can test the API in a different console window with: curl --user enketorules: -d "server_url=https://ona.io/enketo&form_id=widgets" http://localhost:8006/api/v2/survey.

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

Using Docker:

  1. Install Docker Compose.
  2. Set Enketo Express's API key, the linked form and data server, and any additional desired configurations in the file setup/docker/envfile.txt.
  3. Run docker-compose up from project folder and wait until it completes.

The app should now be running on localhost:8005.

How to install a production server

See this tutorial for detailed instructions.

How to configure

All configuration is done in config/config.json. Strictly speaking, this file only has to contain the default properties that you'd like to override, but it might be safer to include all properties. The configuration items have self-explanatory names and helpful sample values. After editing the configuration, the app will need to be restarted.

The default production configuration includes 2 redis instances. 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 might find the vagrant setup steps in bootstrap.sh useful.

For detailed guidance on each configuration item, see this document.

To configure your own custom external authentication also see this section.

API

The API is accessible on /api/v2 and /api/v1. Only API v1 is properly documented at the moment. This temporary note describes the changes introduced by API v2.

How to run

Run with npm start from project root.

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

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

How to update

  • update git repository with git pull (check out a specific release (git tag) for a production server)
  • update dependencies with npm update --production
  • re-build with grunt
  • restart app

Developer tools

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

The easiest way to start the app in development and debugging mode with livereload is with grunt develop.

Browser support

Only the latest modern browser versions are officially supported. The exception is with iOS browsers. Largely, due to Apple's restrictions on third-party browsers, Chrome does not work properly with offline-capable forms. We expect the iOS situation to improve somewhat in the future and are patiently waiting for this.

Enketo endeavors to show a helpful (multi-lingual) error message on unsupported browsers when the form is loaded to avoid serious issues. E.g. Chrome users on iOS will be recommended to switch to Safari when necessary.

Differences with enketo/enketo-legacy

See this doc

Themes

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

The recommended way to customize themes is to either:

  • Create an issue (and fund or send a pull request) for changes to the existing themes, 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 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.

See also this further guidance

Authentication

This app can manage OpenRosa form authentication for protected forms, i.e. it is possible to log in to forms with credentials set in your OpenRosa Server (e.g. Aggregate/KoBo/Ona), just like in ODK Collect.

To make use of OpenRosa form authentication, set the following in config/config.json:

  • linked form and data server -> authentication -> managed by enketo -> true

Alternatively, you could make 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/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://example.com/login?return={RETURNURL}, where {RETURNURL} will be set by enketo.

Security

There are two major security considerations to be aware of. Both of these result in the need to run this application on https with a valid SSL certificate.

API security is mainly arranged by the secret API key set up in config/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/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).

Translation

The user interface was translated by: Tomas Skripcak (Slovak, German), Robert Michael Lundin (Norwegian), Margaret Ndisha, Charles Mutisya (Swahili), Panzero Mauro (Italian), Gabriel Kreindler (Romanian), Jason Reeder, Omar Nazar, Sara Sameer, David Gessel (Arabic), Tino Kreutzer (German), Wasilis Mandratzis-Walz (German, Greek), Luis Molina (Spanish), Martijn van de Rijdt (Dutch).

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

Funding

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, Ona and the HRP project.

License

See the license document for this application's license.

Note that some of the libraries used in this app have different license. In particular note this one.

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.

Change log

See change log