# mdocker
An easy-to-use wrapper for multi-platform Docker image builds.
## Contents
- [mdocker](#mdocker)
- [Contents](#contents)
- [Description](#description)
- [Usage](#usage)
- [Package Compatibility](#package-compatibility)
- [Examples](#examples)
- [Installation](#installation)
- [From PyPI (recommended)](#from-pypi-recommended)
- [Local from source](#local-from-source)
- [No installation, direct run from source](#no-installation-direct-run-from-source)
- [License](#license)
## Description
mdocker is a simple wrapper over Docker Buildx, which can be used for convenient image builds targeted for multiple platforms.
This tool was originally designed as a workaround to a [limitation](https://github.com/docker/buildx/issues/59) that Buildx has with the `--load` parameter.
> [!NOTE]
> *There are, however, some [workarounds and progress](https://github.com/docker/roadmap/issues/371) towards this issue.*
The amount of target platforms specified for this wrapper is equal to the amount of tags generated in local cache.
E.g., if `linux/arm64` and `linux/amd64` were specified as target platforms for the `demo` image, you will get `demo:arm64` and `demo:amd64` built and stored within your local Docker cache.
## Usage
mdocker requires an installation of Python 3.10+.
Below is a help message with the description of arguments.
```help
$ python3 -m mdocker --help
usage: [-h] [--context BCONTEXT] [--file DFILE] [--platforms PLATFORMS] [--push] name
positional arguments:
name specify a name for the image
options:
-h, --help show this help message and exit
--context BCONTEXT specify a path to build context
--file DFILE specify a path to Dockerfile
--platforms PLATFORMS
specify target platforms (e.g., --platforms linux/amd64,linux/arm64)
--push push image to remote registry
```
## Package Compatibility
In some cases, packages for Docker images may not be available across all target platforms.
E.g., a package "some_package" may be available for amd64, but may not be available for arm64 platform.
Is cases like this, you can define custom installation rules within your Dockerfile itself.
An example of such custom rule usage can be found [here](Dockerfile#L16).
Docker's default back-end (BuildKit) provides built-in variables that can be used for determining target platform set for the current build.
The full list of these variables can be found [here](https://docs.docker.com/reference/dockerfile#automatic-platform-args-in-the-global-scope).
## Examples
You can try out mdocker with it's own Dockerfile!
The command below will build the `demo` image for both `amd64` and `arm64` target architectures:
```sh
python3 -m mdocker demo --platforms linux/amd64,linux/arm64
```
Optionally, you can specify paths to the build context and Dockerfile:
```sh
python3 -m mdocker demo --context . --file ./Dockerfile --platforms linux/amd64,linux/arm64
```
## Installation
### From PyPI (recommended)
To install latest mdocker package from PyPI, use:
```sh
python3 -m pip install mdocker
```
### Local from source
To install and debug mdocker locally, in the root of repository use:
```sh
python3 -m pip install -e .
```
### No installation, direct run from source
To run mdocker without any installation into local cache, in the root of repository use:
```sh
export PYTHONPATH=$(pwd)
python3 -m poetry install --no-root
python3 mdocker <arguments>
```
## License
[MIT](#license)
Raw data
{
"_id": null,
"home_page": "https://github.com/seppzer0/mdocker",
"name": "mdocker",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "docker, docker-buildx, multi-platform",
"author": "seppzer0",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/35/f1/a5253dd745e8052f539a599f0dc58d0d3b3df0cb5128f29f237b52b0883c/mdocker-0.3.1.tar.gz",
"platform": null,
"description": "# mdocker\n\nAn easy-to-use wrapper for multi-platform Docker image builds.\n\n## Contents\n\n- [mdocker](#mdocker)\n - [Contents](#contents)\n - [Description](#description)\n - [Usage](#usage)\n - [Package Compatibility](#package-compatibility)\n - [Examples](#examples)\n - [Installation](#installation)\n - [From PyPI (recommended)](#from-pypi-recommended)\n - [Local from source](#local-from-source)\n - [No installation, direct run from source](#no-installation-direct-run-from-source)\n - [License](#license)\n\n## Description\n\nmdocker is a simple wrapper over Docker Buildx, which can be used for convenient image builds targeted for multiple platforms.\n\nThis tool was originally designed as a workaround to a [limitation](https://github.com/docker/buildx/issues/59) that Buildx has with the `--load` parameter.\n\n> [!NOTE]\n> *There are, however, some [workarounds and progress](https://github.com/docker/roadmap/issues/371) towards this issue.*\n\nThe amount of target platforms specified for this wrapper is equal to the amount of tags generated in local cache.\n\nE.g., if `linux/arm64` and `linux/amd64` were specified as target platforms for the `demo` image, you will get `demo:arm64` and `demo:amd64` built and stored within your local Docker cache.\n\n## Usage\n\nmdocker requires an installation of Python 3.10+.\n\nBelow is a help message with the description of arguments.\n\n```help\n$ python3 -m mdocker --help\nusage: [-h] [--context BCONTEXT] [--file DFILE] [--platforms PLATFORMS] [--push] name\n\npositional arguments:\n name specify a name for the image\n\noptions:\n -h, --help show this help message and exit\n --context BCONTEXT specify a path to build context\n --file DFILE specify a path to Dockerfile\n --platforms PLATFORMS\n specify target platforms (e.g., --platforms linux/amd64,linux/arm64)\n --push push image to remote registry\n```\n\n## Package Compatibility\n\nIn some cases, packages for Docker images may not be available across all target platforms.\nE.g., a package \"some_package\" may be available for amd64, but may not be available for arm64 platform.\n\nIs cases like this, you can define custom installation rules within your Dockerfile itself.\n\nAn example of such custom rule usage can be found [here](Dockerfile#L16).\n\nDocker's default back-end (BuildKit) provides built-in variables that can be used for determining target platform set for the current build.\n\nThe full list of these variables can be found [here](https://docs.docker.com/reference/dockerfile#automatic-platform-args-in-the-global-scope).\n\n## Examples\n\nYou can try out mdocker with it's own Dockerfile!\n\nThe command below will build the `demo` image for both `amd64` and `arm64` target architectures:\n\n```sh\npython3 -m mdocker demo --platforms linux/amd64,linux/arm64\n```\n\nOptionally, you can specify paths to the build context and Dockerfile:\n\n```sh\npython3 -m mdocker demo --context . --file ./Dockerfile --platforms linux/amd64,linux/arm64\n```\n\n## Installation\n\n### From PyPI (recommended)\n\nTo install latest mdocker package from PyPI, use:\n\n```sh\npython3 -m pip install mdocker\n```\n\n### Local from source\n\nTo install and debug mdocker locally, in the root of repository use:\n\n```sh\npython3 -m pip install -e .\n```\n\n### No installation, direct run from source\n\nTo run mdocker without any installation into local cache, in the root of repository use:\n\n```sh\nexport PYTHONPATH=$(pwd)\npython3 -m poetry install --no-root\npython3 mdocker <arguments>\n```\n\n## License\n\n[MIT](#license)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Easy-to-use wrapper for multi-platform Docker image builds.",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/seppzer0/mdocker",
"Repository": "https://github.com/seppzer0/mdocker"
},
"split_keywords": [
"docker",
" docker-buildx",
" multi-platform"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ee35445bcb40171ec95e4d406172d8c8fd53147b5dcbe2693729e1f52d60f786",
"md5": "eeba6a31c19f6d9ab6c65bac38d9fe0f",
"sha256": "df9c405e0fe98f8a0dd198fa538b30331adcb5727af95c8952dde8c685d21e83"
},
"downloads": -1,
"filename": "mdocker-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eeba6a31c19f6d9ab6c65bac38d9fe0f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 7445,
"upload_time": "2024-04-12T10:42:35",
"upload_time_iso_8601": "2024-04-12T10:42:35.407468Z",
"url": "https://files.pythonhosted.org/packages/ee/35/445bcb40171ec95e4d406172d8c8fd53147b5dcbe2693729e1f52d60f786/mdocker-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35f1a5253dd745e8052f539a599f0dc58d0d3b3df0cb5128f29f237b52b0883c",
"md5": "b49e61523f370c4738fae1413f9b7fa8",
"sha256": "bfb17b991134cd70a01a385f6df4025a245679703dfc3b6deee5d452c7ae7892"
},
"downloads": -1,
"filename": "mdocker-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "b49e61523f370c4738fae1413f9b7fa8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 10651,
"upload_time": "2024-04-12T10:42:37",
"upload_time_iso_8601": "2024-04-12T10:42:37.684133Z",
"url": "https://files.pythonhosted.org/packages/35/f1/a5253dd745e8052f539a599f0dc58d0d3b3df0cb5128f29f237b52b0883c/mdocker-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 10:42:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "seppzer0",
"github_project": "mdocker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdocker"
}
JSON
