Modus

Container images are intrinsically parameterised, e.g. python:3.9-slim-bullseye is parameterised with Python's version 3.9 and Debian's options slim and bullseye. These parameters can, and often do, depend on and interact with each other and these interactions determine how images are built. Dockerfiles only support parameters as global variables, and do not handle dependencies between them. Developers either hard-code version dependencies or implement ad-hoc Dockerfile generators. For example, Official OpenJDK Docker Images use a combination of Dockerfiles templates with embedded JQ queries, AWK scripts and Bash scripts to support parametrisation.

Modus capitalises on its logic programming foundation to handle parameters and their dependencies in an intuitive, declarative fashion. Modus decreased the size of OpenJDK Docker images build system by 47.6% from scripts written in three languages to a single Modusfile, while reducing the build time by 40.6%.

OpenJDK images case study

This fragment of OpenJDK Dockerfile template combines Dockerfile with two external tools: (1) {{ syntax handled by an AWK script and (2) predicates expressed as JQ queries:

FROM {{
    if is_debian_slim then
        "debian:" + debian_suite + "-slim"
    else
        "buildpack-deps:" + debian_suite + (
        if env.javaType == "jdk" then
            "-scm"
        else
            "-curl"
        end
    )
    end
}}
              

An equivalent Modusfile expresses this fragment without external tools:

debian_image(VARIANT, JAVA_TYPE) :-
    (
        is_debian_slim(VARIANT, DEBIAN_SUITE),
        from(f"debian:${DEBIAN_SUITE}-slim")
    ;
        is_debian(VARIANT),
        debian_suffix_type(SUFFIX, JAVA_TYPE),
        from(f"buildpack-deps:${VARIANT}${SUFFIX}")
    ).
debian_suffix_type("-scm", "jdk").
debian_suffix_type("-curl", "jre").
            

Caching is crucial for optimising build time, because it reuses previously built layers when there are no changes in the build environment and configuration. Caching is only effective when the build system correctly detects cache invalidation. It is a common practice to implement custom build logic by embedding scripts into Dockerfile's RUN instructions. Embedded scripts make cache invalidation imprecise, since any change of the script invalidates the cache even if it is irrelevant to the build target.

Modus statically computes the exact sequence of instructions required to build the target image. This enables users to describe custom logic without sacrificing automatic caching, since Modus does not invalidate cache when irrelevant parts of build logic are modified.

In this Dockerfile, the build profile is selected by an embedded shell script using the argument PROFILE. The build cache for the target PROFILE=debug will be invalidated even if only the irrelevant line make program ; \ is modified:

FROM gcc:bullseye AS app
COPY program.c program.c
ARG PROFILE
RUN if [ "$PROFILE" = "debug" ] ; then \
      CFLAGS=-g make -e program ; \
    else \
      make program ; \
    fi
            

In the equivalent Modusfile, cache invalidation depends on the exact executed commands, therefore a change of the body of make("release") will not invalidate the cache of app("debug"):

app(profile) :-
    from("gcc:bullseye"),
    copy("program.c", "program.c"),
    make(profile).
make("debug") :- run("make -e program")::in_env("CFLAGS", "-g").
make("release") :- run("make program").
            

Just like any code, container build definitions evolve and require maintenance. Dockerfiles do not provide features for modularity and code reuse. Besides, to optimise image size, they require structuring code in an way that many dislike.

Modus supports code evolution and maintenance by providing zero-cost modularity and code reuse. Modus allows users to define their own commands, such as layer building functions or logical predicates, to abstract reusable build workflows. Modus provides a library of builtin predicates to handle common data structures in the build logic. For example, the predicate semver_geq checks if the left version is greater or equal to the right version according to SemVer specification.

List of builtin predicates

Modus provides a library of operators, such as ::in_env for executing commands in a custom environment, that encapsulate build-specific instructions and manipulation of OCI image properties.

List of operators

Using a user-defined predicate install to reuse library installation code:

install(lib, version) :-
    run(f"wget https://example.com/libs/${lib}-v${version}.tar.gz && \
          tar xf ${lib}-v${version}.tar.gz && \
          mv ${lib}-v${version}/ /build"),
    run("cd /build && make install"),
    run(f"rm ${lib}-v${version}.tar.gz && \
          rm -rf /build").

app :-
    from("gcc:latest"),
    install("liba", "1.3.5"),
    install("libb", "4.1").

Using the built-in predicate semver_geq to compare versions of Ubuntu:

base(distr_version, python_version) :-
    semver_geq(distr_version, "16.04"),
    from(f"ubuntu:${distr_version}"),
    run(f"apt-get update && apt-get install -y python${python_version} \
          && rm -rf /var/lib/apt/lists/*").
            

Using the built-in operator ::in_env to execute commands in a custom environment:

app :-
    from("debian:bullseye-slim"),
    (
        run("apt-get update"),
        run("apt-get upgrade"),
        run("apt-get install build-essential")
    )::in_env("DEBIAN_FRONTEND", "noninteractive").