How to install a test/development server
- Install JS prerequisites: Node.js (12.x LTS), Grunt Client.
- Install Redis
- Probably already installed but otherwise, install build-essential, curl and git with
(sudo) apt-get install build-essential git curl
- Install dependencies for Puppeteer (for PDF creation only)
- Clone this repository
- Create config/config.json. See How To configure.
- Install dependencies and build with
npm installfrom the project root
This takes several shortcuts. Do not use for production!
- Install Vagrant and VirtualBox
vagrant upfrom project folder and wait until it completes *
- Log in to the VM with
vagrant sshand 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.
vagrant up fails for reasons beyond our control - e.g. if external resources are temporarily unavailable. Try running
vagrant reload --provision to resolve this.
- Install Docker Compose.
- Create a config file at
config/config.jsonspecifying at minimum an API key.
- (Optional) For HTTPS, copy your SSL certificate and key files to
setup/docker/secrets/ssl.keyrespectively (take care not to commit these files back to any public git repository). Plain HTTP requests to Enketo Express will be automatically redirected to HTTPS.
docker-compose up -dfrom the
setup/dockerdirectory and wait to see e.g.
Worker 1 ready for duty....
- To stop, execute
docker-compose stopfrom the
setup/dockerdirectory. Database dumps from the main Redis instance will be mapped into the directory
The app should now be running on localhost.
How to install a production server
How to configure
All configuration is normally done in config/config.json. This file only has to contain the default properties that you'd like to override. For some it may be preferable to include all properties, to avoid surprises when the default configuration changes. Others may want to reduce hassle and keep the config.json as small as possible to automatically deploy configuration changes (e.g. new widgets). After editing the configuration, the app will need to be restarted.
As an alternative, there is an option to use environment variables instead of a config/config.json file. If the config/config.json file is missing Enketo will assume configuration is done with environment variables. A combination of both options is not supported. See config/sample.env for more information on equivalent environment variable names.
The default production configuration includes 2 redis instances. You can greatly simplify installation by using 1 redis instance instead (for development 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 development usages, it is helpful to set "linked form and data server" -> "server url" to
"", so you can use any OpenRosa server with your local Enketo Express.
If you'd like to run a form server such as KoBoToolbox or ODK Aggregate or ODK Central on a private IP address during development, you need to add that IP address to "ip filtering" -> "allowIPAddressList".
For detailed guidance on each configuration item, see 10-configuration.
To configure your own custom external authentication also see this document.
How to run
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))
How to enable debug logs
Enketo uses the npm
debug module. All debug statements are prefixed with
enketo: and will not appear unless the environment variable is set. To enable debugging logs for enketo specifically, set
DEBUG as follows: