Setting Up and Working in the Local Environment

Development of the application starts by being able to build and run Web Reflectivity in the developer’s computer, termed the Local Environment, or just LOCAL.

The top-level Makefile contains macros (make targets) that liberates the developer from having to remember the various terminal conda and docker commands. Typing make help will show the list of macros with a short description.

$ make help
$ build-docker  build the image for the package under src/
$ clean         deletes containers, network, volumes, and images
$ conda         installs, then activates conda environment webrefl with all dependencies
$ dev           installs the local dev environment for the first time. Requires sudo privileges if the 'docker' group doesn't exist or if you don't belong nto such group.
$ docs          create HTML docs under docs/_build/html/. Requires activation of the webrefl conda environment
$ redev         reinstalls the local dev environment after the cleaning step
$ startdev      invoke docker-compose to create images, instantiate containers, and start services
$ test          run unit tests

Web Reflectivity is fully containerized so nothing except the docker engine and docker-compose is needed to install in the developer’s computer in order to compose and run the software. However, it is highly recommended to create first the conda environment containing the dependencies and do the development work in that environment. Command make conda will create conda environment webrfl with all needed dependencies. In addition, it will install the src/web_reflectivity package in development mode.

Configuration

As part of the configuration setp, the developer needs to export the following environment variables to the shell:

  • LDAP_SERVER_URI

  • LDAP_USER_DN_TEMPLATE

  • LDAP_DOMAIN_COMPONENT

These value of these variables are secrets allowing the developer to login to Web Reflectivity with their UCAMS account. The developer must contact the development team to procure themselves with these variables. A convenient place to store them is in an .envrc file at the root level of the source code. See utility direnv for how .envrc files are used. A minimalistic .envrc file would look like this:

$ export LDAP_SERVER_URI=*****
$ export LDAP_USER_DN_TEMPLATE=*****
$ export LDAP_DOMAIN_COMPONENT=*****

where the ***** are placeholders for the actual values.

Next, command make dev is the entrypoint to configuring LOCAL and starting it for the first time.

  • create a “docker” UNIX group if non-existent. This requires sudo privileges.

  • add the developer’s username to the “docker” group so that the developer can run docker commands.

  • login to the code.ornl.gov container registry. You will need the UCAMS credentials for this.

  • create directories under /tmp/log/web_reflectivity/ to mount the /var/log/ directories of each service. This allows the developer to peruse the logs without having to log into each container.

  • compose and start all services specified in cfg/docker-compose.localdev.yml

For details regarding configuring Docker in a Linux box, see Docker post-installation. Subsequent builds of the software should be not performed with make dev.

Running the Application

After Web Reflectivity starts, the developer can point the browser to localhost and start using the service. See the manual fit session example for usage.

There are several ways to stop the running service:

  • Ctrl-C will gently stop the containers, nothing more.

  • docker-compose down -v will stop and remove the containers, as well as networks and volumes.

  • make clean will invoke docker-compose down -v and then remove all images.

To restart the service, one can:

  • docker-compose up –build

  • make startdev will overwrite the docker-compose.yml file with docker-compose.local.yml, then invoke docker-compose up –build.

  • make redev will invoke make clean, then make startdev

Recreating the images is time consuming so the typical development cycle is:

  1. docker-compose down -v

  2. make some changes to the code

  3. docker-compose up –build

Notice, however, that src/ is mounted on the container running Web Reflectivity so any changes to the python source will automatically reflect in the application. Hence, there will be no need to stop, then restart the service for the changes to take effect.

Unit Testing

To run the unit tests, activate the webrefl conda environment. To run all tests, invoke make test.

To run individual tests:

$ cd src
$ DJANGO_SETTINGS_MODULE='web_reflectivity.settings.unittest' pytest fitting/tests.py -k 'test_file_list'