[][src]Crate dockerfile


Build Status Crates.io docs.rs License Crates.io Crates.io

A Rust library for dynamically generating Dockerfiles.

The use case this crate was originally built for was to build Docker images from a worker service running in Kubernetes for client workloads. This is definitely not the only pattern that is supported. The generated Dockerfiles could be persisted somewhere or discarded immediately after use. The containers generated are standard containers, built according to the Dockerfiles you generated.

All of the Dockerfile instructions are supported in raw form as of 2018.12.09. There is an issue open to add more structured and type-safe interfaces for the instructions which need it.

get started

First you will need to add this to your Cargo.toml dependencies.

dockerfile = "0.2"

Now you can start building Dockerfiles.

use dockerfile::{

fn main() {
    // Build up a new Dockerfile.
    let dockerfile = Dockerfile::base("rust:${RUST_VERSION}-slim")
        .push(Copy::new("/static ./static"))
        .push(Cmd::new("echo 'Hello. Goodbye.'"))

    // Write it out as a string.
    let output = dockerfile.to_string();
FROM rust:${RUST_VERSION}-slim
COPY /static ./static
CMD echo 'Hello. Goodbye.'


I would like to have this crate offer a type-safe interface for constructing the various Dockerfile instructions. This will help reduce bugs which could only be found once you actually attempt to invoke the docker build. I would like to experiment with adding constructors for the various forms of instructions; EG, offer a constructor for CMD which takes an impl Iterator<Item=AsRef<str>> for building the form CMD ["arg0", "arg1"] &c.



The ADD instruction copies new files, directories or remote file URLs from <src> and adds them to the filesystem of the image at the path <dest>.


The ARG instruction defines a variable that users can pass at build-time to the builder with the docker build command using the --build-arg <varname>=<value> flag.


The main purpose of a CMD is to provide defaults for an executing container.


The COPY instruction copies new files or directories from <src> and adds them to the filesystem of the container at the path <dest>.


Parser directives are optional, and affect the way in which subsequent lines in a Dockerfile are handled.


A Dockerfile represented in code.


A Dockerfile builder.


An ENTRYPOINT allows you to configure a container that will run as an executable.


The ENV instruction sets the environment variable <key> to the value <value>.


The EXPOSE instruction informs Docker that the container listens on the specified network ports at runtime.


The FROM instruction initializes a new build stage and sets the base image for subsequent instructions.


The HEALTHCHECK instruction tells Docker how to test a container to check that it is still working.


The LABEL instruction adds metadata to an image.


The ONBUILD instruction adds to the image a trigger instruction to be executed at a later time, when the image is used as the base for another build. The trigger will be executed in the context of the downstream build, as if it had been inserted immediately after the FROM instruction in the downstream Dockerfile.


The RUN instruction will execute any commands in a new layer on top of the current image and commit the results.


The SHELL instruction allows the default shell used for the shell form of commands to be overridden.


The STOPSIGNAL instruction sets the system call signal that will be sent to the container to exit.


The USER instruction sets the user name (or UID) and optionally the user group (or GID) to use when running the image and for any RUN, CMD and ENTRYPOINT instructions that follow it in the Dockerfile.


The VOLUME instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other containers.


The WORKDIR instruction sets the working directory for any RUN, CMD, ENTRYPOINT, COPY and ADD instructions that follow it in the Dockerfile.



An enum representing all of the different types of Dockerfile instructions available.