Local Development Environment

Because Dokomo Forms uses Docker, setting up a local development environment is easy. If you're not familiar with Docker, we suggest you read up on it a bit in order to get an understanding of how it works.

Overview

Dokomo Forms uses Docker Compose, which is Docker's way of wiring up multiple containers, each running a specified service, to form a single application. In the case where we're running Dokomo Forms for local development, we have two containers, one for the database service (mdillon/postgis) and one for the Tornado web application (selcolumbia/dokomoforms).

The Dokomo Forms repo has two Docker Compose configuration files, one for development (docker-compose-dev.yml) and a second for a 'production' environment (docker-compose.yml) which includes a third NGINX container.

The development configuration maps the local working directory — i.e. the source code — to the /dokomo directory on the web app container. This makes it easy to continue working with your normal development workflow and tools, and have the changes reflected in the running web application.

Setup Steps

1. Install Docker Compose

2. Fork the Dokomo Forms Repo

3. In a terminal, navigate to the repo, and run $ docker-compose -f docker-compose-dev.yml up -d.

4. Once Docker Compose is finished installing and setting up the containers and dependencies, you can navigate to localhost:8888, where the Dokomo Forms web application should be available.

Local Configuration

Configuration settings for the web application can be set by creating a local_config.py file in the root of the project. Take a look at the local_config.py.example file for the available configuration options.

Building the Front End Code

The front end source code is built using Gulp. The compiled source files are not included in the repository, so you'll need to build them locally.

1. Install node

2. Install gulp globally by running $ sudo npm install -g gulp.

3. Navigate to the repo root directory, and install the npm dependencies by running $ npm install

4. Finally, run $ gulp dev-build to build the front end code.

If you're actively working on the front end code, you can simply run $ gulp. This default gulp task is set up to watch the front end source files and rebuild them when they change.

Running Tests

Assuming you're running the application using Docker, as outlined above, running the tests must be done from within the webapp Docker container.

1. Find the id of the webapp Docker container: $ docker ps
2. Access the shell of the container: $ docker exec -i -t [webapp id] /bin/bash
3. Start a new instance of the webapp which will be accessed by selenium: $ ./tests/python/selenium_webapp.py
4. Prepare the testing environment (i.e. install dependencies): $ source ./tests/prepare_docker_testing_environment.sh
5. Run the tests: $ tox

If you want to run code coverage, you can do so by running $ tox -e cover.

If you want to exit tests on the first failure, run $ tox -e failfast.