.. _local environment:

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

.. code-block:: bash

   $ 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 <https://direnv.net/>`_ for how `.envrc` files are used.
A minimalistic `.envrc` file would look like this:

.. code-block:: bash

   $ 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 <https://docs.docker.com/engine/install/linux-postinstall/>`_.
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 :ref:`the manual fit session example <a manual fit session>` 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:

.. code-block:: bash

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