Software we use: Docker

Docker

Developers of the OSCAL project are encouraged to rely on a shared Docker image to ensure their environment is consistent with the rest of the team and CI/CD. Currently developers can choose to build the image themselves, or use the private Docker registry.

Note: currently the Docker registry is only accessible to members of the csd773 Docker Hub organization for administrative reasons, though we hope to make the registry public at some point.

Obtaining the image from the registry

If you are a OSCAL team member that does not have an account with Docker Hub that has access to the csd773 organization, ask on the team Gitter for instructions.

Otherwise, logging in is simple.

Using Docker desktop

If you are using Docker desktop, simply sign in via the button the top right corner.

Using the Docker CLI

Run the following command and follow the instructions:

docker login

Pulling the image

Once you have logged in, simply pull the image as follows:

docker pull csd773/oscal-common-env:develop

Building the image manually

Building the image locally is simple:

# From the root of the OSCAL project
# Force uninitialize submodules (optional)
# git submodule deinit -f .
# Ensure your submodules are up to date with the current commit
git submodule update --init --recursive
# Build the image
./build/build-oscal-env-dockerfile.sh

The script build-oscal-env-dockerfile.sh will tell you the built image's tag. E.g.

# Script output from build-oscal-env-dockerfile.sh
Built and tagged csd773/oscal-common-env:fixed-a-thing, to push run:
    docker push csd773/oscal-common-env:fixed-a-thing

Note that the tag of the built image is derived from your current branch name. For more details see "Controlling the Docker image in CI".

Using the image

To run a single command within the container run the following, replacing csd773/oscal-common-env:fixed-a-thing with the desired tag:

docker run \
    -v $(pwd):/oscal \
    csd773/oscal-common-env:fixed-a-thing \
    your-command-here

To run an interactive session, prepend the -it flags and do not put a command:

docker run -it \
    -v $(pwd):/oscal \
    csd773/oscal-common-env:fixed-a-thing

In both of these scenarios, the Docker image is passed the current working directory (e.g. the root of the repository) and maps it to /oscal in the container.

For more options like port mapping (required to access the Hugo serve web server), consult the Docker documentation

Controlling the Docker image in CI

In the future we plan to rely on Docker images for CI/CD more. GitHub actions workflows that depend on the Docker images use the csd773 registry (building locally each run would take forever). Because of this, GitHub workflows relying on CI will attempt to:

1. Pull the image with a tag corresponding to the current branch of the PR
2. Pull the image with the develop tag

This is done to provide users with an "escape hatch" for modifying the environment within a PR.

Users that have logged in to the Docker registry can build and push new images as follows:

1. Build the image as instructed in the "Building the image manually" section

2. Push the resulting tagged image to the registry as instructed by the script output:

   docker push csd773/oscal-common-env:$TAG # where $TAG is the tag of your built image