[][src]Crate dockerfile

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::{
    Dockerfile,
    Arg,
    Copy,
    Cmd,
};

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

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

development

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.

Structs

Add

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>.

Arg

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.

Cmd

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

Copy

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

Directive

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

Dockerfile

A Dockerfile represented in code.

DockerfileBuilder

A Dockerfile builder.

Entrypoint

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

Env

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

Expose

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

From

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

Healthcheck

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

Label

The LABEL instruction adds metadata to an image.

Onbuild

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.

Run

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

Shell

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

Stopsignal

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

User

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.

Volume

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.

Workdir

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

Enums

Instruction

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