Package: dbyml
docker-build-yaml (dbyml)Docker-build-yaml (dbyml) is a CLI tool to build a docker image with build options loaded from yaml. Instead of running thedocker buildwith many options, write options in config file, build your docker image with them. It helps you to manage build process more readable and flexible.Table of contentsTable of contentsInstallUsagePreparationCreate Dockerfile and Configuration file.BuildBuild-args and Labels(Experimental) Multi-platform buildExampleConfigurationConfig fileUpdate from v1.2.0Docker hostENV variablesMulti-stage buildPush to repositoryUsing TLSMulti-platform buildOther settingsInstall$ pip install dbymlUsagePreparationTo use dbyml, Docker Engine must be installed on host for build and run docker commands without root privileges (as non-root user) on client. Refer toManage Docker as a non-root userorDocker rootless modefor non-root user setting.Create Dockerfile and Configuration fileTo build your image from Dockerfile, you must make Dockerfile and config file where the build options to be passed to docker command are listed . For example, we will make the followingDockerfileanddbyml.ymlin the same directory.DockerfileDbyml does not required any settings about Dockerfile, so you can write according toDockerfile reference.FROMalpine:latestARGkey1RUNecho"$key1">arg.txt&&\catarg.txt&&\rmarg.txt# You can write any processdbyml.ymlThis is a config file used by dbyml.The image name fieldnameis required.The image tag fieldtagis optional. Default value islatest.To setARG key1in the Dockerfile, Setbuild_argsfield and key name and its value in config.---image:name:myimagetag:v1.0build_args:key1:"Thisissetbydbyml."BuildRun dbyml to build the image from your Dockerfile.$ dbymlThe imagemyimage:v1.0will be created after successfully build.If Dockerfile and config file are not in the same directory, you must set path to the Dockerfile withpathfield in the config.---image:name:myimagetag:v1.0path:path/to/DockerfileDbyml has other options for build. See each subsection for more details.Set build-args and labels in imagePush the image to a private registryMulti-platform buildBuild-args and LabelsIf you want to set build-args and labels on building, Setbuild-argsandlabelfields as list of key-value pairs in config.---image:name:myimagetag:v1.0build-args:myarg1:aaamyarg2:bbblabel:mylabel:cccauthor:me"my.domain.com":corporationsThe above configuration is corresponding to the followingdocker buildcommand.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(Experimental) Multi-platform buildDbyml can build multi-platform image with docker buildx. At first, you need to install buildx in order to enable this feature (Seedocker docs buildxfor installation). After installing, make sure that can run buildx commands such asdocker buildx versionwith no error.The multi-platform build on dbyml are executed with docker buildx by the follow steps.Create an instance and node for multi-platform building withdocker buildx create.Build an image on the node withdocker buildx build.Push the image to a private registry written in config file.Pull the image from the registry (optional).Remove the instance (optional).To build your image with multi-platform by dbyml, Thebuildxand theregistryfields are required in config. See example below.ExampleIf you want to make an image that works forlinux/amd64,linux/arm64andlinux/arm/v7, Set list of these values inbuildx.platformin config. The example config is the following. You will make the image with the tagmyregistry:5000/dbyml-sample:latest, push it to the private registrymyregistry:5000.image:name:dbyml-samplepath:.dockerfile:Dockerfileregistry:enabled:truehost:"myregistry.com"port:"5000"buildx:enabled:trueinstance:multi-builderuse_existing_instance:falseplatform:-linux/amd64-linux/arm64-linux/arm/v7type:registrypull_output:trueremove_instance:falseIf save the configuration above asdbyml.yml, you can run simply dbyml command to build the image.# In the same directory as dbyml.yml$dbyml# In the different directory$dbyml-cpath/to/dbyml.ymlAfter successfully building the image, The imagemyregistry:5000/dbyml-sample:latestwill be pushed to the registry and pull automatically from the registry on your host when setpull_outputtrue. So check that the image manifest includes platformsamd64,arm64andarm/v7.$ docker manifest inspect myregistry:5000/dbyml-sample:latest{"schemaVersion":2,"mediaType":"application/vnd.docker.distribution.manifest.list.v2+json","manifests":[{"mediaType":"application/vnd.docker.distribution.manifest.v2+json","size":739,"digest":"sha256:1bc3ae24a9c6322a628254ad06accf994334f9e9609764d45dc904ae4d8f1a2a","platform":{"architecture":"amd64","os":"linux"}},{"mediaType":"application/vnd.docker.distribution.manifest.v2+json","size":739,"digest":"sha256:4afc068927d499f90f6a8721d0f819daa1654dff3250383fd7300d03855b1e85","platform":{"architecture":"arm64","os":"linux"}},{"mediaType":"application/vnd.docker.distribution.manifest.v2+json","size":739,"digest":"sha256:eca5fe836c0014d253004cc538e3bf3df77a3a897cf62fb15f407cced704336f","platform":{"architecture":"arm","os":"linux","variant":"v7"}}]}The instance used for buildmulti-builderand its nodemulti-builder0remain after successfully build since setremove_instance: falsein config. The build caches will be used on the build of the image including the same layers. If automatically remove these instance after build, setremove_instance: true.$ docker buildx ls
NAME/NODE        DRIVER/ENDPOINT             STATUS  PLATFORMS
multi-builder *  docker-container                    
  multi-builder0 unix:///var/run/docker.sock running linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/386Settings for registryThe addition fields may be required in config file according to the registry settings.Insecure registryIf the registry are insecure such as HTTP registry, setconfig.http: trueunderbuildxfield in config file as below.registry:enabled:truehost:"my-insecure-registry.com"port:"5000"buildx:enabled:trueinstance:multi-builderuse_existing_instance:falseplatform:-linux/amd64-linux/arm64-linux/arm/v7type:registrypull_output:trueremove_instance:falseconfig:http:trueSelf-signed certificatesIf the registry uses self-signed certificates, set path to the CA certificate inca_certunderregistryfield in config file as below.registry:enabled:truehost:"self-signed_registry.com"port:"5000"ca_cert:certs/ca_cert.pembuildx:enabled:trueinstance:multi-builderuse_existing_instance:falseplatform:-linux/amd64-linux/arm64-linux/arm/v7type:registrypull_output:trueremove_instance:falseResolve registry IPBuild and push are executed on buildx node (docker container), so the node may fail to resolve IP address of the registry. There are two ways to resolve it.Setdriver_opt.network: hostunderbuildxfield in config file as below. With this config, hosts in/etc/hostson host will be added into /etc/hosts in the node.Set List of hostname and ip address inadd_hostunderbuildxfield in config file. The list will be addedd into/etc/hostsin the node.registry:enabled:truehost:"myregistry.com1"port:"5000"buildx:enabled:trueinstance:multi-builderuse_existing_instance:falseplatform:-linux/amd64-linux/arm64-linux/arm/v7type:registrypull_output:trueremove_instance:falsedriver_opt:network:hostadd_host:myregistry.com1:192.168.3.100ConfigurationThe behavior of dbyml is managed by the config file written in yaml syntax.Config fileDbyml automatically searches for config filedbyml.ymlordbyml.yamlin the execution directory. If you want to use other filename or path, you need run dbyml with-coption to specify path to the config.$ dbyml -c [path_to_config_file]To gerenate a sample config to build your docker image in local, rundbyml --init. The configdbyml.ymlwill be generated in the current directory by interactively specifying the values of the fields. You can edit the contents of the config later.$ dbyml --initRundbymlwith--init -qoptions to generate the config non-interactively.$ dbyml --init -qUpdate from v1.2.0The contents and syntax in config file has changed since v1.3.0. To Run--convertoption in order to convert old config to the new one. The converted configdbyml.ymlwill be generated, so edit it according to your configuration.$ dbyml --convert [path/to/old/config]Docker hostDocker_host under image field specify a docker daemon to connect from client. The default value isunix:/var/run/docker.sock, which means connect to docker daemon on local. Set hostname (or ip address) including protocol and port if you want to build your image on remote docker host.# Exampleimage:# Connect to docker daemon on local.docker_host:"unix:/var/run/docker.sock"# Connect to 10.10.10.20:2375 with tcp.# docker_host: "tcp://10.10.10.20:2375"ENV variablesYou 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 buildTargetfield specify the name of the phase to build in multi-stage builds. SeeUse multi-stage buildsfor more details on multi-stage builds.image:name:myimagetag:v1.0target:init-stagePush to repositoryDbyml supports to push the image todocker registry v2in local.To push the image to be built from your Dockerfile, Theregistryfields are required in config. You must set the hostname (or ip address) and port of the registry. Settingenabledto true enables these settings. Setting to false disables the settings, which means dose not push the image after building.image:name:myimagetag:v1.0registry:enabled:truehost:"myregistry"# Registry hostname or ip addressport:"5000"# Registry portRunningdbymlwith the config will make the docker imagemyimage:v1.0, then push it to the registry as the image name ofmyregistry:5000/myimage:v1.0.
You can check that the image has been successfully pushed to the registry such asregistry API.If you want to add more hierarchy in repository, setnamespacefield in config. The image will be pushed as{hostname}:{port}/{namespace}/{name}:{tag}.image:name:myimagetag:v1.0registry:enabled:truehost:"myregistry"# Registry hostname or ip addressport:"5000"# Registry portnamespace:myspaceIf you use the basic authentication to access to the registry build byNative basic auth, you need setusernameandpasswordfields under push in the config.image:name:myimagetag:v1.0registry:enabled:trueusername:${username}password:${password}host:"myregistry"# Registry hostname or ip addressport:"5000"# Registry portUsing TLSTo build your image on docker host using TLS (HTTPS), Set the paths to the CA certificate, client certificate and key in each field and enabled to true undertlsfield. SeeDocker documentationabout connection to TLS docker daemon.tls:enabled:trueca_cert:ca.pemclient_cert:cert.pemclient_key:key.pemMulti-platform buildDbyml usesdocker buildxfor multi-platform build. The settings about are managed bybuildxsection in config file. The supported fields are below. Seesample.ymlto check how to write these values.keytyperequireddescriptionenabledboolrequiredWhether to enable buildxtypestrrequiredOutput type of build image. Onlyregistryis supported now.platformlistrequiredList of platformsinstancestroptionalAn instance name used on builduse_existing_instancebooloptionalWhether to use the instance with the same name as specified ininstancefield if exists. When false, the instance will be recreated.pull_outputbooloptionalWhether to pull the image from the registry after build.remove_instancebooloptionalWhether to remove an instance after build.Other settingsSeesample.ymlfor supported fields.