Planks for Docker

Planks are a highly configurable patch format for Docker images that provide effortless plug-in support for existing Docker images. Designed to enable extensibility for scientific computing platforms, they're best suited to enabling highly reproducible custom environments for containers similar to NextGen in a Box.

Warning

Planks are arbitrary Dockerfile code that will be executed by the Docker build engine. Before using a plank, always be sure to review its constituent plankfiles!

How Planks Work

Planks for Docker operates on a three-layered hierarchy of data entities: plankfiles, planks, and planksets. These files are used to specify where each plank should insert new commands into plank gaps in the Dockerfile that's been targeted for patching.

Plankfiles and Plank Gaps

Plankfiles (*.plankfile)are the smallest units of planks, consisting of snippets of Dockerfile code. Each plankfile's filename corresponds to a plank gap in the target Dockerfile, which tells Planks for Docker where the plankfile's contents should be inserted. Plank gaps consist of a single-line comment of the form #@plank_file_name, so they won't interfere with the way your container builds.

If using multiple build stages, it is strongly recommended to place plank gaps at the ends of build stages. This will make the output file easier to navigate.

Planks

Each plankfile belongs to a parent folder called a plank. Planks are best thought of as individual plug-ins. In addition to containing plankfiles, each plank folder also contains plank_conf.yml, where the following values should be defined:

• plank_name: A unique identifier for the plank. Note that multiple planks of the same name cannot be loaded.
• plankset_name: A name corresponding to the target plankset, or environment, that the plank is designed for. Used to ensure that planks are only loaded within their intended containers. Planks can easily be shared with others as ZIP archives, making it easy and convenient to distribute lightweight plug-in packages.

Planksets

In order to use planks, they are placed into a folder called a plankset. The plankset also contains a configuration folder that is responsible for defining how the planks' patches will be applied:

• plankset_name: The name of the plankset.
• apply_nested_stages: Whether plankfiles should be isolated into their own nested build stages, as a boolean value.
  • For projects that do not use build stages, this should always be false.
  • For projects that use build stages, this setting is recommended as a way to improve the organization of the output Dockerfile. However, note Planks for Docker dynamically generates names for new build stages, which may cause issues for some workflows.
• target_path: A path to the target Dockerfile that patches should be applied to. Note that this is non-destructive; the original target Dockerfile will not be modified unless set as the output destination.
• destination_path: The path where Planks for Docker should output its patched Dockerfile after applying the contents of the plankset. The contents of this path will be overwritten, so please be careful to avoid overwriting important data.
• planks_path: The path to the folder containing the plankset. Including plankset_conf.yml in the plankset folder is strongly preferred, so this should nearly always be ./.
• exclude: A YML-formatted list of plank_name values to exclude from the patching process. Useful for research and development environments where testing different combinations of planks is necessary.

Usage

All actions taken by the executable are specified by the plankset. For testing purposes, an example plankset is provided in the examples directory of this repository.

When Planks for Docker finishes patching, it will output a patched Dockerfile to the destination_path from plankset_conf.yml. This Dockerfile can then be built in a similar manner to the source Dockerfile.

Via native executable

planks_docker [path to plankset_conf.yml]

Via container

For portability, Planks for Docker can also be run via a Docker container, as hosted on DockerHub at sheargrub/planks_docker. Consider using a pinned version tag (e.g. v1.0) if integrating Planks for Docker into standalone tooling. docker run --rm -it -v "{/directory/containing/plankset/}:/host_data/" "sheargrub/planks_docker:latest" "/host_data/{path/to/plankset_conf.yml}" Note that relative paths are strongly encouraged when configuring Planks for Docker to run via container.

Building

Build native executable

From the repository root: cargo build --release

Build container

From the docker folder of this repository: docker build -t sheargrub/planks_docker:dev .

For published releases, be sure to build for multi-platform support: docker build -t sheargrub/planks_docker:release --platform linux/amd64,linux/arm64 .