URO-187: Docker containers for developer support

This set of changes introduces three Docker support features I relied upon in a set of changes for improved Europa / kbase-ui support. I’m separating them out to reduce the size and cognitive load of that future PR.

The Docker support falls into three categories:

• Visual Studio Code (VSC) devcontainer
• a node container for carrying out tasks
• a docker compose file for ease of launching a Europa image for local usage

VSC devcontainer

VSC devcontainers have become very popular, almost a de-facto standard for development. Other development platforms, like those offered by Jetbrains, are beginning to offer a similar feature.

For those unfamiliar, a devcontainer provides an integration between the IDE and a Docker container which provides support for developing within the container environment, both with a familiar developer experience.

The developer experience offers all of the IDE benefits, such as syntax coloring, tooltips, language server, plugins, but running inside of a docker container. This allows all of these tools to be run in a consistent environment across all developer host machines. Consistency in this case includes e.g., node, npm, and git. In addition, automation tools like scripts run in a consistent Linux environment, avoiding compatibility issues with host machine utilities like bash. As a result, the developer does not need to install these tools on their host machine, nor ensure that the versions are consistent.

For the developer, a devcontainer experience is very similar to that of developing straight on the host machine. One caveat is that in VSC the local filesystem is not accessible via the user interface; e.g. copying and pasting files from host to container does not work.

In this repo, the devcontainer shares a Dockerfile with the node container described below, located in ./tools/node/Dockerfile.

A devcontainer may be started with the following technique on macOS:

• open the project in VSC
• Use the following key combination: Shift-Command-P
• Search for and select “Dev Containers: Reopen in Container”
• To exit the devcontainer, similarly search for and select “Dev Containers: Reopen Folder Locally”

Once in the devcontainer, one may engage in the typical development workflow, including:

• install npm dependencies
• maintain npm dependencies
• run the dev server

Since the devcontainer mounts the repo directory all the expected files are available.

Node container for tasks

Another useful job for Docker containers is to run tasks. Typically, at least in my experience, this involves shell and/or interpreted language programs running tasks such as linting and compiling. In this repo, it uses npm and shell scripts to run common tasks, like installing npm dependencies, running tests, and building the bundled web app.

The benefits are the usual - no need to install the same version of tool on each developer host machine. In addition, it offers the ability to operate with a minimal difference from the GHA environment.

The repo is mounted into the container at the directory /app, which is set as the working directory.

The node container will accept any command available to it. Since the repo is mounted into the container, npm and shell scripts area available and may be run. In addition, a bash shell may be opened, allowing one to operate directly in the container.

To invoke the tool:

./tools/node/run COMMAND

The following node tasks have been used:

• ./tools/node/run npm ci to install from the npm lock file
• ./tools/node run npm install to install from packages.json when it has changed
• ./tools/node/run ./scripts/test to run unit tests
• ./tolls/node/run ./scripts/build to build the variety of deployment builds
• ./tools/node/run ./scripts/build_deploy.sh to build with the old deployment build script

Of course, scripts could be added to make these command lines shorter.

Docker compose for local server

In order to utilize a local image based on the top level Dockerfile, a top level docker-compose.yml file has been added. This file assists in running a container based on the same small nginx image used in kbase deployment environments. This is useful for validating the web app across environments (although the usefulness is not complete as running it within a docker network via the kbase-ui proxy)

To use it:

# Install build dependencies
./tools/node/run npm ci

# Build
./tools/node/run ./scripts/build

# Run
STATIC_ENVIRONMENT=ci ./scripts/server

Additional .env files

This file provides an “environment file” to provide environment variables to the CRA-based web app. These environment variables are consumed as the code is transpired to JavaScript, and used essentially as template placeholders. That is, they are substituted into the code text. This means, for example, that a string value must be surrounded by quotes.

The repo currently provides a single env file for ci-europa. I’ve added additional files to support all development environments. This assists in using the web app, in development mode, against all KBase deployment environments.

Each of the additional env files is named .env-ENV; e.g. .env-ci.

Because CRA by default uses the file named .env, in order to utilize a different environment, simply copy/paste the contents of the desired env file into .env. (Yes, this is rather crude, but does not introduce any additional dependencies or code.)

Running with kbase-ui

The support included in this set of changes does allow Europa to run alongside kbase-ui on the developer machine, either in developer mode (i.e. in a devcontainer, running the development server), or with the deployment image.

I’m going to leave this out of scope of this set of changes, but do note that the docker compose network settings are in place for this specific purpose -- so that Europa, kbase-ui, and kbase services can be installed on a local Docker network named kbase-dev.

This requires the kbase-ui proxy, and some additional configuration, and an updated version of kbase-ui (for Europa support), so this will be addressed in a future PR.