{"id":19482533,"url":"https://github.com/git-ogawa/dbyml","last_synced_at":"2026-04-09T23:44:43.410Z","repository":{"id":40298257,"uuid":"486647264","full_name":"git-ogawa/dbyml","owner":"git-ogawa","description":"CLI tool to help docker build","archived":false,"fork":false,"pushed_at":"2023-01-16T16:39:46.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-08T07:26:15.187Z","etag":null,"topics":["docker","python","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-ogawa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-28T15:20:56.000Z","updated_at":"2022-04-29T08:11:51.000Z","dependencies_parsed_at":"2023-02-10T04:46:08.412Z","dependency_job_id":null,"html_url":"https://github.com/git-ogawa/dbyml","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdbyml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdbyml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdbyml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdbyml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-ogawa","download_url":"https://codeload.github.com/git-ogawa/dbyml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240718428,"owners_count":19846478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","python","yaml"],"created_at":"2024-11-10T20:11:00.188Z","updated_at":"2026-04-09T23:44:43.384Z","avatar_url":"https://github.com/git-ogawa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docker-build-yaml (dbyml)\n\n![License](https://img.shields.io/github/license/git-ogawa/dbyml)\n[![Version](https://img.shields.io/pypi/v/dbyml)](https://pypi.python.org/pypi/dbyml/)\n[![Python versions](https://img.shields.io/pypi/pyversions/dbyml)](https://pypi.python.org/pypi/dbyml/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n[![Downloads](https://static.pepy.tech/badge/dbyml)](https://pepy.tech/project/dbyml)\n\nDocker-build-yaml (dbyml) is a CLI tool to build a docker image with build options 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.\n\n# Table of contents\n- [Install](#install)\n- [Usage](#usage)\n  - [Prerequisite](#prerequisite)\n  - [Create Dockerfile and Configuration file](#create-dockerfile-and-configuration-file)\n  - [Build an image](#build-an-image)\n  - [Run using docker](#run-using-docker)\n  - [Build-args and Labels](#build-args-and-labels)\n  - [(Experimental) Multi-platform build](#experimental-multi-platform-build)\n  - [Example](#example)\n    - [Settings for registry](#settings-for-registry)\n    - [Insecure registry](#insecure-registry)\n    - [Self-signed certificates](#self-signed-certificates)\n    - [Resolve registry IP](#resolve-registry-ip)\n- [Configuration](#configuration)\n  - [Config file](#config-file)\n    - [Update from v1.2.0](#update-from-v120)\n  - [Docker host](#docker-host)\n  - [ENV variables](#env-variables)\n  - [Multi-stage build](#multi-stage-build)\n  - [Push to repository](#push-to-repository)\n  - [Using TLS](#using-tls)\n  - [Multi-platform build](#multi-platform-build)\n  - [Other settings](#other-settings)\n\n\n# Install\n```\n$ pip install dbyml\n```\n\n# Usage\n\n## Prerequisite\nTo 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 to [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) or [Docker rootless mode](https://docs.docker.com/engine/security/rootless/) for non-root user setting.\n\n## Create Dockerfile and Configuration file\nTo 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 following `Dockerfile` and `dbyml.yml` in the same directory.\n\n- Dockerfile\n    - Dbyml does not required any settings about Dockerfile, so you can write according to [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).\n\n```Dockerfile\nFROM alpine:latest\nARG key1\nRUN echo \"$key1\" \u003e arg.txt \u0026\u0026 \\\n    cat arg.txt \u0026\u0026 \\\n    rm arg.txt\n\n# You can write any process\n```\n\n- dbyml.yml\n    - This is a config file used by dbyml.\n    - The image name field `name` is required.\n    - The image tag field `tag` is optional. Default value is `latest`.\n    - To set `ARG key1` in the Dockerfile, Set `build_args` field and key name and its value in config.\n```yaml\n---\nimage:\n    name: myimage\n    tag: v1.0\n    build_args:\n        key1: \"This is set by dbyml.\"\n```\n\n\n## Build an image\nRun dbyml to build the image from your Dockerfile.\n\n```\n$ dbyml\n```\n\nThe image `myimage:v1.0` will be created after successfully build.\n\nIf Dockerfile and config file are not in the same directory, you must set path to the Dockerfile with `path` field in the config.\n```yaml\n---\nimage:\n    name: myimage\n    tag: v1.0\n    path: path/to/Dockerfile\n```\n\nDbyml has other options for build. See each subsection for more details.\n\n- [Set build-args and labels in image](#build-args-and-labels)\n- [Push the image to a private registry](#push-to-repository)\n- [Multi-platform build](#experimental-multi-platform-build)\n\n\n## Run using docker\nTo run dbyml in docker container, mount the followings paths on host to the container on build.\n\n- `/var/run/docker.sock` required to use the docker engine on host in a container.\n- `${PWD}` A directory containing a Dockerfile and dbyml.yml must be mounted in container. See the example below.\n\n\nGenerate a configuration file `dbyml.yml`.\n```\n$ docker run --rm -it \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v ${PWD}:/work \\\n  docogawa/dbyml:latest --init -q\n\n# Change owner if needed.\n$ sudo chown ${USER}:${USER} dbyml.yml\n```\n\nBuild a image from Dockerfile and dbyml.yml in the current directory.\n```\n# Check that Dockerfile and dbyml.yml exist.\n$ ls -1 .\nDockerfile\ndbyml.yml\n\n# Build a image.\n$ docker run --rm -it \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v ${PWD}:/work \\\n  docogawa/dbyml:latest\n```\n\n\n\n## Build-args and Labels\nIf you want to set build-args and labels on building, Set `build-args` and `label` fields as list of key-value pairs in config.\n\n```yaml\n---\nimage:\n    name: myimage\n    tag: v1.0\n    build-args:\n        myarg1: aaa\n        myarg2: bbb\n    label:\n        mylabel: ccc\n        author: me\n        \"my.domain.com\": corporations\n```\n\nThe above configuration is corresponding to the following `docker build` command.\n```\ndocker build -t myimage:v1.0 . \\\n    --build-arg myarg1=aaa --build-arg myarg2=bbb \\\n    --label mylabel=ccc --label author=me --label my.domain.com=corporations\n```\n\n\n## (Experimental) Multi-platform build\nDbyml can build multi-platform image with docker buildx. At first, you need to install buildx in order to enable this feature (See [docker docs buildx](https://docs.docker.com/buildx/working-with-buildx/) for installation). After installing, make sure that can run buildx commands such as `docker buildx version` with no error.\n\nThe multi-platform build on dbyml are executed with docker buildx by the follow steps.\n\n1. Create an instance and node for multi-platform building with `docker buildx create`.\n1. Build an image on the node with `docker buildx build`.\n1. Push the image to a private registry written in config file.\n1. Pull the image from the registry (optional).\n1. Remove the instance (optional).\n\nTo build your image with multi-platform by dbyml, The `buildx` and the `registry` fields are required in config. See example below.\n\n## Example\nIf you want to make an image that works for `linux/amd64`, `linux/arm64` and `linux/arm/v7`, Set list of these values in `buildx.platform` in config. The example config is the following. You will make the image with the tag `myregistry:5000/dbyml-sample:latest`, push it to the private registry `myregistry:5000`.\n\n```yaml\nimage:\n  name: dbyml-sample\n  path: .\n  dockerfile: Dockerfile\n\nregistry:\n  enabled: true\n  host: \"myregistry.com\"\n  port: \"5000\"\n\nbuildx:\n  enabled: true\n  instance: multi-builder\n  use_existing_instance: false\n  platform:\n    - linux/amd64\n    - linux/arm64\n    - linux/arm/v7\n  type: registry\n  pull_output: true\n  remove_instance: false\n```\n\nIf save the configuration above as `dbyml.yml`, you can run simply dbyml command to build the image.\n```shell\n# In the same directory as dbyml.yml\n$ dbyml\n\n# In the different directory\n$ dbyml -c path/to/dbyml.yml\n```\n\nAfter successfully building the image, The image `myregistry:5000/dbyml-sample:latest` will be pushed to the registry and pull automatically from the registry on your host when set `pull_output` true. So check that the image manifest includes platforms `amd64`, `arm64` and `arm/v7`.\n\n```yaml\n$ docker manifest inspect myregistry:5000/dbyml-sample:latest\n{\n   \"schemaVersion\": 2,\n   \"mediaType\": \"application/vnd.docker.distribution.manifest.list.v2+json\",\n   \"manifests\": [\n      {\n         \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n         \"size\": 739,\n         \"digest\": \"sha256:1bc3ae24a9c6322a628254ad06accf994334f9e9609764d45dc904ae4d8f1a2a\",\n         \"platform\": {\n            \"architecture\": \"amd64\",\n            \"os\": \"linux\"\n         }\n      },\n      {\n         \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n         \"size\": 739,\n         \"digest\": \"sha256:4afc068927d499f90f6a8721d0f819daa1654dff3250383fd7300d03855b1e85\",\n         \"platform\": {\n            \"architecture\": \"arm64\",\n            \"os\": \"linux\"\n         }\n      },\n      {\n         \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n         \"size\": 739,\n         \"digest\": \"sha256:eca5fe836c0014d253004cc538e3bf3df77a3a897cf62fb15f407cced704336f\",\n         \"platform\": {\n            \"architecture\": \"arm\",\n            \"os\": \"linux\",\n            \"variant\": \"v7\"\n         }\n      }\n   ]\n}\n```\n\n\nThe instance used for build `multi-builder` and its node `multi-builder0` remain after successfully build since set `remove_instance: false` in config. The build caches will be used on the build of the image including the same layers. If automatically remove these instance after build, set `remove_instance: true`.\n```\n$ docker buildx ls\nNAME/NODE        DRIVER/ENDPOINT             STATUS  PLATFORMS\nmulti-builder *  docker-container\n  multi-builder0 unix:///var/run/docker.sock running linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/386\n```\n\n### Settings for registry\nThe addition fields may be required in config file according to the registry settings.\n\n### Insecure registry\nIf the registry are insecure such as HTTP registry, set `config.http: true` under `buildx` field in config file as below.\n```yaml\nregistry:\n  enabled: true\n  host: \"my-insecure-registry.com\"\n  port: \"5000\"\n\nbuildx:\n  enabled: true\n  instance: multi-builder\n  use_existing_instance: false\n  platform:\n    - linux/amd64\n    - linux/arm64\n    - linux/arm/v7\n  type: registry\n  pull_output: true\n  remove_instance: false\n  config:\n    http: true\n```\n\n### Self-signed certificates\nIf the registry uses self-signed certificates, set path to the CA certificate in `ca_cert` under `registry` field in config file as below.\n```yaml\nregistry:\n  enabled: true\n  host: \"self-signed_registry.com\"\n  port: \"5000\"\n  ca_cert: certs/ca_cert.pem\n\nbuildx:\n  enabled: true\n  instance: multi-builder\n  use_existing_instance: false\n  platform:\n    - linux/amd64\n    - linux/arm64\n    - linux/arm/v7\n  type: registry\n  pull_output: true\n  remove_instance: false\n```\n\n### Resolve registry IP\nBuild 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.\n\n1. Set `driver_opt.network: host` under `buildx` field in config file as below. With this config, hosts in `/etc/hosts` on host will be added into /etc/hosts in the node.\n1. Set List of hostname and ip address in `add_host` under`buildx` field in config file. The list will be addedd into `/etc/hosts` in the node.\n\n```yaml\nregistry:\n  enabled: true\n  host: \"myregistry.com1\"\n  port: \"5000\"\n\nbuildx:\n  enabled: true\n  instance: multi-builder\n  use_existing_instance: false\n  platform:\n    - linux/amd64\n    - linux/arm64\n    - linux/arm/v7\n  type: registry\n  pull_output: true\n  remove_instance: false\n  driver_opt:\n    network: host\n  add_host:\n    myregistry.com1: 192.168.3.100\n```\n\n\n\n# Configuration\nThe behavior of dbyml is managed by the config file written in yaml syntax.\n\n\n## Config file\nDbyml 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.\n\n```\n$ dbyml -c [path_to_config_file]\n```\n\n\nTo 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.\n```\n$ dbyml --init\n```\n\nRun `dbyml` with `--init -q` options to generate the config non-interactively.\n```\n$ dbyml --init -q\n```\n\n### Update from v1.2.0\nThe 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.\n\n```\n$ dbyml --convert [path/to/old/config]\n```\n\n\n## Docker host\nDocker_host under image field specify a docker daemon to connect from client. The default value is `unix:/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.\n\n```yaml\n# Example\nimage:\n    # Connect to docker daemon on local.\n    docker_host: \"unix:/var/run/docker.sock\"\n\n    # Connect to 10.10.10.20:2375 with tcp.\n    # docker_host: \"tcp://10.10.10.20:2375\"\n```\n\n\n\n## ENV variables\nYou 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.\n\n```yaml\nimage:\n    name: ${BASEIMAGE_NAME}\n    tag: ${VERSION:-latest}\n```\n\n## Multi-stage build\n`Target` field specify the name of the phase to build in multi-stage builds. See [Use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) for more details on multi-stage builds.\n\n```yaml\nimage:\n    name: myimage\n    tag: v1.0\n    target: init-stage\n```\n\n\n## Push to repository\nDbyml supports to push the image to [docker registry v2](https://hub.docker.com/_/registry) in local.\n\n\nTo 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.\n\n```yaml\nimage:\n    name: myimage\n    tag: v1.0\n\nregistry:\n    enabled: true\n    host: \"myregistry\" # Registry hostname or ip address\n    port: \"5000\" # Registry port\n```\n\nRunning `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`.\nYou can check that the image has been successfully pushed to the registry such as [registry API](https://docs.docker.com/registry/spec/api/).\n\n\nIf you want to add more hierarchy in repository, set `namespace` field in config. The image will be pushed as `{hostname}:{port}/{namespace}/{name}:{tag}`.\n\n```yaml\nimage:\n    name: myimage\n    tag: v1.0\n\nregistry:\n    enabled: true\n    host: \"myregistry\" # Registry hostname or ip address\n    port: \"5000\" # Registry port\n    namespace: myspace\n```\n\n\nIf you use the basic authentication to access to the registry build by [Native basic auth](https://docs.docker.com/registry/deploying/#native-basic-auth), you need set `username` and `password` fields under push in the config.\n\n```yaml\nimage:\n    name: myimage\n    tag: v1.0\n\nregistry:\n    enabled: true\n    username: ${username}\n    password: ${password}\n    host: \"myregistry\" # Registry hostname or ip address\n    port: \"5000\" # Registry port\n```\n\n\n## Using TLS\nTo 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 under `tls` field. See [Docker documentation](https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket) about connection to TLS docker daemon.\n\n```yaml\ntls:\n  enabled: true\n  ca_cert: ca.pem\n  client_cert: cert.pem\n  client_key: key.pem\n```\n\n## Multi-platform build\nDbyml uses [docker buildx](https://github.com/docker/buildx) for multi-platform build. The settings about are managed by `buildx` section in config file. The supported fields are below. See [sample.yml](sample/sample.yml#L121) to check how to write these values.\n\n| key | type | required | description |\n| - | - | - | - |\n| enabled | bool | required | Whether to enable buildx |\n| type | str | required | Output type of build image. Only `registry` is supported now. |\n| platform | list | required | List of platforms |\n| instance | str | optional | An instance name used on build |\n| use_existing_instance | bool | optional | Whether to use the instance with the same name as specified in `instance` field if exists. When false, the instance will be recreated. |\n| pull_output | bool | optional | Whether to pull the image from the registry after build. |\n| remove_instance | bool | optional | Whether to remove an instance after build. |\n\n\n## Other settings\nSee [sample.yml](sample/sample.yml) for supported fields.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ogawa%2Fdbyml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-ogawa%2Fdbyml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ogawa%2Fdbyml/lists"}