dbyml 1.3.0

"CLI tool for building docker image"

• docker-build-yaml (dbyml)
• Install
• Usage
  • Preparation
  • Build
  • Build-args and Labels
• Configuration
  • Config file
    • Update from v1.2.0
  • ENV variables
  • Multi-stage build
  • Push to repository
  • Other settings

docker-build-yaml (dbyml)

docker-build-yaml (dbyml) is a CLI tool to build a docker image with arguments loaded from yaml. Instead of running the docker build with many options, write options in config file, build your docker image with them. It helps you to manage build process more readable and flexible.

Install

pip install dbyml

Usage

Preparation

Dbyml is useful for building your docker image. To build an image, you must make your Dockerfile and config file where the build arguments are listed. For example, we will make the example Dockerfile and dbyml.yml in the same directory.

• Dockerfile
  • Dbyml does not required any settings about Dockerfile, so you can write according to Dockerfile reference.

FROM alpine:latest
ARG key1
RUN echo "$key1" > arg.txt && \
    cat arg.txt && \
    rm arg.txt

# You can write any process

• dbyml.yml
  • This is a config file used by dbyml.
  • The image name field name is required.
  • The image tag field tag is optional. Default value is latest.
  • To set ARG key1 in the Dockerfile, Set build_args field and key name and its value in config.

---
image:
    name: myimage
    tag: v1.0
    build_args:
        key1: "This is set by dbyml."

Build

Run dbyml to build the image from your Dockerfile.

dbyml 

The image myimage:v1.0 will be created after successfully building the image.

If Dockerfile and config file are not in the same directory, you must set path to the Dockerfile with path field in the config.

---
image:
    name: myimage
    tag: v1.0
    path: path/to/Dockerfile

Build-args and Labels

If you want to set build-args and labels on building, Set build-args and label fields as list of key-value pairs in config.

---
image:
    name: myimage
    tag: v1.0
    build-args:
        myarg1: aaa
        myarg2: bbb
    label:
        mylabel: ccc
        author: me
        "my.domain.com": corporations

The above configuration is corresponding to the following docker build command.

docker build -t myimage:v1.0 . \
    --build-arg myarg1=aaa --build-arg myarg2=bbb \
    --label mylabel=ccc --label author=me --label my.domain.com=corporations

Configuration

The behavior of dbyml is managed by the config file written in yaml syntax.

Config file

Dbyml automatically searches for config file dbyml.yml or dbyml.yaml in the execution directory. If you want to use other filename or path, you need run dbyml with -c option to specify path to the config.

dbyml -c [path_to_config_file]

To gerenate a sample config to build your docker image in local, run dbyml --init. The config dbyml.yml will be generated in the current directory by interactively specifying the values of the fields. You can edit the contents of the config later.

dbyml --init

Run dbyml with --init -q options to generate the config non-interactively.

dbyml --init -q

Update from v1.2.0

The contents and syntax in config file has changed since v1.3.0. To Run --convert option in order to convert old config to the new one. The converted config dbyml.yml will be generated, so edit it according to your configuration.

dbyml --convert [path/to/old/config]

ENV variables

You can use environment variable expressions in config. ${VAR_NAME} and setting default_value ${VAR_NAME:-default_value} are supported. Error occurs when the specified env is undefined.

---
image:
    name: ${BASEIMAGE_NAME}
    tag: ${VERSION:-latest}

Multi-stage build

Target field specify the name of the phase to build in multi-stage builds. See Use multi-stage builds for more details on multi-stage builds.

image:
    name: myimage
    tag: v1.0
    target: init-stage

Push to repository

Dbyml supports to push the image to docker registry v2 in local.

To push the image to be built from your Dockerfile, The registry fields are required in config. You must set the hostname (or ip address) and port of the registry. Setting enabled to true enables these settings. Setting to false disables the settings, which means dose not push the image after building.

---
image:
    name: myimage
    tag: v1.0

registry:
    enabled: true
    host: "myregistry" # Registry hostname or ip address 
    port: "5000" # Registry port

Running dbyml with the config will make the docker image myimage:v1.0, then push it to the registry as the image name of myregistry:5000/myimage:v1.0. You can check that the image has been successfully pushed to the registry such as registry API.

If you want to add more hierarchy in repository, set namespace field in config. The image will be pushed as {hostname}:{port}/{namespace}/{name}:{tag}.

---
image:
    name: myimage
    tag: v1.0

registry:
    enabled: true
    host: "myregistry" # Registry hostname or ip address 
    port: "5000" # Registry port
    namespace: myspace

If you use the basic authentication to access to the registry build by Native basic auth, you need set username and password fields under push in the config.

---
image:
    name: myimage
    tag: v1.0

registry:
    enabled: true
    username: ${username}
    password: ${password}
    host: "myregistry" # Registry hostname or ip address 
    port: "5000" # Registry port

Other settings

See sample.yml for supported fields.