Skip to content

deployment-dev.md

Latest commit

 

History

History
164 lines (116 loc) · 5.68 KB

deployment-dev.md

File metadata and controls

164 lines (116 loc) · 5.68 KB
Raw

Deployment for local development

(Table of contents automatically generated by https://luciopaiva.com/markdown-toc/).

IMPORTANT: This section may be slightly out of date.

Configuration

See Configuration.

Introduction

Using Docker for development is an expedient to avoid refactoring the code to simplify its relationship to climpyrical and improve the way data files are addressed. Avoiding the refactoring comes at some significant cost in Docker complication, a cost which in the initial phases of this project was worth the benefit, but which now outweighs it.

The dve-dev-local Docker image is the primary means for running the app while developing and debugging. Using it has two advantages:

  • It is very similar to the production environment.
  • It reduces effort needed to install the supporting software.
  • It maps a development configuration file onto config.yml. Typically, this configuration has a reduced dataset to speed startup, and uses local copies of large files ditto.

This image enables the developer to run the app in a Docker container, but with "live" code updates visible inside the container. All infrastructure for building and running this image is in docker/dev-local.

The image is normally built locally. (Because of this, there is no automated build for the dev-local image as there is for the production image.) The image installs the dependencies listed in Pipfile and Pipfile.lock, but does not install dash-dev-explorer. The image need only be rebuilt when project dependencies (Pipfile, Pipfile.lock) change.

After building, the image is run locally, and the local codebase for dash-dv-explorer is mounted to it. The container's first step (via the ENTRYPOINT) is to install that local codebase. With this arrangement, changes to the local codebase are available directly inside the container. The container does not need to be restarted, nor does the image need to be rebuilt in order to test code changes.

With the container running, the developer can run commands from inside it by using docker exec commands. Most convenient is to use docker exec to run an interactive bash shell in the container. From that bash shell all ordinary commands can be run, including running tests and running the app.

Instructions

  1. Advance prep

    Do each of the following things once per workstation.

    1. Configure Docker user namespace mapping.

      1. Clone pdp-docker.

      2. Follow the instructions in the pdp-docker documentation: Setting up Docker namespace remapping (with recommended parameters).

      3. Grant permissions on the downloads directory:

      setfacl -m "g:dockremap1000:rwx" docker/dev-local/downloads/
      1. Create and grant permissions on the DVE log file:
      touch dve_log.txt
setfacl -m "g:dockremap1000:rw" dve_log.txt

      Why is this necessary? This file is mounted to the dve-dev-local Docker container. A file mount that does not exist is automatically created by Docker, but it creates a directory, not a file. A file must be created in advance, and given suitable permissions if it is to be written to.

    2. Update the development config (docker/dev-local/config.yml) as needed.

    3. Copy any large datasets (e.g., reconstructions) to your local codebase (typically under local-data/). This cuts app startup time from minutes to seconds. App startup is incurred every time you make a change to the codebase and want to see the results.

  2. Build the image

    The image need only be (re)built when the project is first cloned and when Pipenv changes. To build the image:

    docker-compose -f docker/dev-local/docker-compose.yml build

    The image name is pcic/dve-dev-local.

  3. Start the container

    docker-compose -f docker/dev-local/docker-compose.yml up -d

    The container name is dve-dev-local.

  4. Connect to a bash shell inside the container

    When the container is running, you can connect to it and run a bash shell inside it with

    docker exec -it dve-dev-local bash

    You will see a prompt like

    dockremap@f4bcdc72b9f2:/codebase#

    At this prompt you can enter bash commands, including the following:

  5. Start the app inside the container

    From the container bash prompt:

    pipenv run python /codebase/app.py --debug

    The --debug option does two things: Runs the server with debug=True, and defaults the logging level to DEBUG.

    Aside: Dash apps are based on Flask. Flask documentation strongly recommends running apps for development using the Flask command line flask run. Unfortunately, that does not work for a Dash app, and we must run using a Python script as above.

    This enables the development environment, including the interactive debugger and reloader, and then starts the server on http://localhost:5000/.

    For more details, see the link above.

  6. Stop the container

    When you have completed a cycle of development and testing, you may wish to stop the Docker container.

    docker-compose -f docker/dev-local/docker-compose.yml down