# README
ibuilder is a [cli](https://en.wikipedia.org/wiki/Command-line_interface) based builder of [docker](https://hub.docker.com/) images. It provides an interface for building and pushing the image, signing images, as well as for tagging source code after build with a build version and other common image tasks.
### Latest Changes
- package updates: docker, packing, pydantic, requests, rich
### NOTICES
- version 1.0.0+ requires python 3.11+ (for internal toml processing capabilities and its fast)
### Features
- build: build docker images
- push: push images to any container registry
- sign: sign images for container signing and verification
- source control: tag and push when you build an image
- history: retain build history for quick/easy access to past build info
- quick/easy: create an `ibuilder.toml` file and run `ib build -i minor` to build, push, commit to source control and sign a new image
### Requirements
- python 3
- docker: docker must be set up as it is used to build and push the image
- git: (optional) if you use the source-tag feature you will need git installed and your code setup in git (it simply performs a git tag && git push from the working directory)
- image signor: (optional) if you choose to sign images a signor (such as cosign) is needed
### Overview
- setup (see #setup)
- configure (see #configure): place a copy of the `example/.ibuilder.toml` in the same directory as your Dockerfile of the app you want to build and adjust it as needed
- run (see #run): execute ibuilder to build/push/tag a version of your app, its as simple as `ib build`
### Install
We recommend using [pipx](https://github.com/pypa/pipx) to install ibuilder: `pipx install ibuilder`. You can also install via pip: `pip install --user ibuilder`.
### Setup
ibuilder uses a config file to store your setup. Each 'app' you build with ibuilder expects this file to be in the 'root' of the app that you are building. This file contains information such as whether to build, push, tag the image, labels to apply, Dockerfile to use, etc. You can grab an example config file from [ibuilder/example/.ibuilder.toml](https://gitlab.com/drad/ibuilder/-/blob/master/example/.ibuilder.toml).
### Configure
- create a project config file
- place a copy of the `example/.ibuilder.toml` file in your project (same directory as your Dockerfile) and configure as needed
### Features
If you create an arg with the name "BUILD_VERSION" its value will be replaced with the build version of the current build. This can be used to pass the build version from ibuilder into your docker environment.
### Run
- basic run: `ib build --version=1.2.3`
- the above command assumes there is a `.ibuilder.toml` in the current working directory which happens to be in the same directory as the Dockerfile which you wish to build
- change logging level: `LOG_LEVEL=DEBUG ib build...`
+ standard python log levels supported: CRITICAL|ERROR|WARNING|INFO|DEBUG (default is INFO)
View help with `ib --help` or see help for a specific command: `ib build --help`.
### Recommendations
We recommend using docker's configuration storage for reg_auth-* related configuration items as it encrypts sensitive information and is likely already configured (if you have already used `docker login`). If you leave the remaining items empty the default values will be used. This will then try `$HOME/.docker/config.json` and `$HOME/.dockercfg` for your docker config settings. If you do not already have a docker config run `docker login` and it should be created for you. After a successful login you should not need to do anything else for the application as the needed info will be stored in your dockercfg and the app will use it when needed.
If you are signing your images you may want to set the `COSIGN_PASSWORD` environment variable in your `~/.bashrc` or equivalent shell config file to avoid being prompted for your signing password after build and push. It should be noted that you will be prompted twice (if you are pushing both the build version and the `latest` tag of this version) as ib signs both tags of the built image. To avoid this we recommend setting the `COSIGN_PASSWORD` environment variable but please ensure you understand the security implications of doing so.
### Legacy
This project originally started under the name boi - builder of images and as such you may find references to boi and even backward support for boi (e.g. local history database, user config file, etc.).
### Links
- [typer](https://typer.tiangolo.com/)
- [docker](https://pypi.org/project/docker/)
- [docs](https://docker-py.readthedocs.io/en/stable/)
- [toml](https://pypi.org/project/toml/)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/drad/ibuilder",
"name": "ibuilder",
"maintainer": "drad",
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": "sa@adercon.com",
"keywords": "cli, docker, containers, build, ci, cd, image, tag, git, push, sign, cosign",
"author": "drad",
"author_email": "sa@adercon.com",
"download_url": "https://files.pythonhosted.org/packages/8e/c4/089375c1d2d569e3b1f43373f3e27c75fc79327385e64bc31cf3ac5ce6ad/ibuilder-3.9.0.tar.gz",
"platform": null,
"description": "# README\n\nibuilder is a [cli](https://en.wikipedia.org/wiki/Command-line_interface) based builder of [docker](https://hub.docker.com/) images. It provides an interface for building and pushing the image, signing images, as well as for tagging source code after build with a build version and other common image tasks.\n\n\n### Latest Changes\n\n- package updates: docker, packing, pydantic, requests, rich\n\n### NOTICES\n\n- version 1.0.0+ requires python 3.11+ (for internal toml processing capabilities and its fast)\n\n\n### Features\n\n- build: build docker images\n- push: push images to any container registry\n- sign: sign images for container signing and verification\n- source control: tag and push when you build an image\n- history: retain build history for quick/easy access to past build info\n- quick/easy: create an `ibuilder.toml` file and run `ib build -i minor` to build, push, commit to source control and sign a new image\n\n\n### Requirements\n\n- python 3\n- docker: docker must be set up as it is used to build and push the image\n- git: (optional) if you use the source-tag feature you will need git installed and your code setup in git (it simply performs a git tag && git push from the working directory)\n- image signor: (optional) if you choose to sign images a signor (such as cosign) is needed\n\n\n### Overview\n\n- setup (see #setup)\n- configure (see #configure): place a copy of the `example/.ibuilder.toml` in the same directory as your Dockerfile of the app you want to build and adjust it as needed\n- run (see #run): execute ibuilder to build/push/tag a version of your app, its as simple as `ib build`\n\n\n### Install\n\nWe recommend using [pipx](https://github.com/pypa/pipx) to install ibuilder: `pipx install ibuilder`. You can also install via pip: `pip install --user ibuilder`.\n\n\n### Setup\n\nibuilder uses a config file to store your setup. Each 'app' you build with ibuilder expects this file to be in the 'root' of the app that you are building. This file contains information such as whether to build, push, tag the image, labels to apply, Dockerfile to use, etc. You can grab an example config file from [ibuilder/example/.ibuilder.toml](https://gitlab.com/drad/ibuilder/-/blob/master/example/.ibuilder.toml).\n\n\n### Configure\n\n- create a project config file\n - place a copy of the `example/.ibuilder.toml` file in your project (same directory as your Dockerfile) and configure as needed\n\n\n### Features\n\nIf you create an arg with the name \"BUILD_VERSION\" its value will be replaced with the build version of the current build. This can be used to pass the build version from ibuilder into your docker environment.\n\n\n### Run\n\n- basic run: `ib build --version=1.2.3`\n - the above command assumes there is a `.ibuilder.toml` in the current working directory which happens to be in the same directory as the Dockerfile which you wish to build\n- change logging level: `LOG_LEVEL=DEBUG ib build...`\n + standard python log levels supported: CRITICAL|ERROR|WARNING|INFO|DEBUG (default is INFO)\nView help with `ib --help` or see help for a specific command: `ib build --help`.\n\n\n### Recommendations\n\nWe recommend using docker's configuration storage for reg_auth-* related configuration items as it encrypts sensitive information and is likely already configured (if you have already used `docker login`). If you leave the remaining items empty the default values will be used. This will then try `$HOME/.docker/config.json` and `$HOME/.dockercfg` for your docker config settings. If you do not already have a docker config run `docker login` and it should be created for you. After a successful login you should not need to do anything else for the application as the needed info will be stored in your dockercfg and the app will use it when needed.\n\nIf you are signing your images you may want to set the `COSIGN_PASSWORD` environment variable in your `~/.bashrc` or equivalent shell config file to avoid being prompted for your signing password after build and push. It should be noted that you will be prompted twice (if you are pushing both the build version and the `latest` tag of this version) as ib signs both tags of the built image. To avoid this we recommend setting the `COSIGN_PASSWORD` environment variable but please ensure you understand the security implications of doing so.\n\n\n### Legacy\n\nThis project originally started under the name boi - builder of images and as such you may find references to boi and even backward support for boi (e.g. local history database, user config file, etc.).\n\n\n### Links\n\n- [typer](https://typer.tiangolo.com/)\n- [docker](https://pypi.org/project/docker/)\n - [docs](https://docker-py.readthedocs.io/en/stable/)\n- [toml](https://pypi.org/project/toml/)",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "build, tag, and push docker images",
"version": "3.9.0",
"project_urls": {
"Homepage": "https://gitlab.com/drad/ibuilder",
"Repository": "https://gitlab.com/drad/ibuilder"
},
"split_keywords": [
"cli",
" docker",
" containers",
" build",
" ci",
" cd",
" image",
" tag",
" git",
" push",
" sign",
" cosign"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a769001fc7a509c18229808190567778fac7e783b52d95da20326012abdf48d",
"md5": "069ca2630b3c74739407defa8b9511d8",
"sha256": "2e90472f67da3c41ba4f5cc72379b7e673265bafcd44d86901a9c469ea17ec9f"
},
"downloads": -1,
"filename": "ibuilder-3.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "069ca2630b3c74739407defa8b9511d8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 30939,
"upload_time": "2024-11-07T18:15:36",
"upload_time_iso_8601": "2024-11-07T18:15:36.997974Z",
"url": "https://files.pythonhosted.org/packages/4a/76/9001fc7a509c18229808190567778fac7e783b52d95da20326012abdf48d/ibuilder-3.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ec4089375c1d2d569e3b1f43373f3e27c75fc79327385e64bc31cf3ac5ce6ad",
"md5": "b13166cbae242d1b7b4691355dd54046",
"sha256": "ce1bc77c6d2627febf115e5edb7339e7cc4578ec684090237c905f078778b320"
},
"downloads": -1,
"filename": "ibuilder-3.9.0.tar.gz",
"has_sig": false,
"md5_digest": "b13166cbae242d1b7b4691355dd54046",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 28354,
"upload_time": "2024-11-07T18:15:38",
"upload_time_iso_8601": "2024-11-07T18:15:38.571116Z",
"url": "https://files.pythonhosted.org/packages/8e/c4/089375c1d2d569e3b1f43373f3e27c75fc79327385e64bc31cf3ac5ce6ad/ibuilder-3.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-07 18:15:38",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "drad",
"gitlab_project": "ibuilder",
"lcname": "ibuilder"
}
JSON