Build process is a step required by werf to build images defined in the werf configuration.

Dockerfile image

Werf uses Dockerfile as a main way to describe how to build an image. Image built with Dockerfile will be referred to as dockerfile image (more info about dockerfile image).

How dockerfile image built

To build dockerfile image werf creates a single stage called dockerfile.

How dockerfile stage is built:

  1. Stage signature is calculated based on specified Dockerfile and its context. This signature represents result image state.
  2. If image with this signature already exists in the stages storage, then werf does not issue a new docker build.
  3. If image with this signature is not found in the stage storage, then werf issues a regular docker build. Werf uses usual build command of builtin docker client (same as in docker build command). Local docker cache will be created and used as usually with the regular docker client.
  4. After docker image is built werf puts result dockerfile stage into stages storage (by tagging result docker image with a calculated signature) when using :local stages storage.

See configuration artictle for the werf.yaml configuration details.

Stapel image and artifact

Werf also has an alternative way to build images with so called stapel builder, which:

  • Provides integration with git and incremental rebuilds based on the git repo history.
  • Allows using of ansible tasks to describe instructions needed to build the image.
  • Allows sharing a common cache between builds with mounts.
  • Reduces image size by detaching source data and build tools.

Image built with stapel builder will be referred to as stapel image.

See stapel image and stapel artifact articles for more details.

How stapel images and artifacts built

Each stapel image or artifact consists of a some number of stages. The same mechanics used to build every stage.

To build a stage werf generates instructions list needed to build this stage. Instructions depend on the concrete stage type and may contain internal service commands generated by werf itself along with user specified shell commands. For example werf may generate instructions to apply a prepared patch from mounted text file using git cli util.

All generated instructions to build current stage are supposed to be run in a container based on the previous stage. This container will be referred to as build container.

To build a stage werf runs prepared instructions list in the build container based on the previous stage. The resulting container state is then committed as a new stage and saved into the stages storage.

Werf has a special service image called flant/werf-stapel which contains a chroot /.werf/stapel with all tools and libraries needed to build images with stapel builder. More info about stapel image are available in the article.

flant/werf-stapel is mounted into every build container so that all precompiled tools are available in every stage build and may be used in instructions list.

How stapel builder processes CMD and ENTRYPOINT

To build stage image werf launches a container with service CMD and ENTRYPOINT and then substitutes ones with the base image values. If the base image does not have the value werf resets service to the special empty value:

  • [] for CMD;
  • [""] for ENTRYPOINT.

Also, werf uses the special empty value instead of base image ENTRYPOINT if a user specifies CMD (docker.CMD).

Otherwise, werf works like docker according to documentation.

Multiple builds on the same host

Multiple build commands can run at the same time on the same host. When building stage Werf acquires a lock using stage signature as ID so that only one build process is active for a stage with a particular signature at the same time.

When another build process is holding a lock for a stage, Werf waits until this process releases a lock. Then Werf proceeds to the next stage.

The reason is: no need to build the same stage multiple times. Werf build process can wait until another process finishes build and puts stage into the stages storage.