Update image build instructions after Builder deprecation, add blog post #3027
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| --- | ||
| author: Jan Čermák | ||
| authorURL: https://github.com/sairon | ||
| authorImageURL: https://avatars.githubusercontent.com/u/211416?s=96&v=4 | ||
| title: "Migrating app builds to Docker BuildKit" | ||
| --- | ||
|
|
||
| The legacy `home-assistant/builder` container and the old `home-assistant/builder` GitHub Action have been retired. We recommend to migrate all app (formerly add-on) repositories to allow direct build with Docker BuildKit and to use the new composite actions described in this post. | ||
|
|
||
| ## What changed and why | ||
|
|
||
| The old builder ran every architecture build inside a single privileged Docker-in-Docker container using QEMU emulation. This was slow, required elevated privileges, and those who were already familiar with Docker needed to learn how to use the custom Home Assistant's builder container. This also had unnecessary maintenance overhead as the builder can be currently fully replaced with Docker BuildKit, which is natively supported on GitHub Actions runners and has built-in multi-arch support with QEMU emulation when needed. | ||
agners marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| For your CI, the replacement is a set of focused [composite GitHub Actions](https://github.com/home-assistant/builder) that delegate building to the runner's native Docker with Docker BuildKit. Outside the CI, the migration means that your `Dockerfile` is now the single source of truth for building your app image, and you can use `docker build` directly to build and test your app locally without needing to use the builder container. | ||
|
|
||
| ## Migration process | ||
sairon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### Before (legacy action) | ||
|
|
||
| Previously, you may have had a single step in your GitHub Actions workflow that looked like this: | ||
|
|
||
| ```yaml | ||
| - name: Build | ||
| uses: home-assistant/builder@master | ||
| with: | ||
| args: | | ||
| --all \ | ||
| --target /data \ | ||
| --docker-hub my-org \ | ||
| --docker-user my-org \ | ||
| --docker-password ${{ secrets.DOCKER_PASSWORD }} | ||
| ``` | ||
|
|
||
| ### After (composite actions) | ||
|
||
|
|
||
| Replace the above with the three composite actions. See the [example workflow](https://github.com/home-assistant/apps-example/blob/main/.github/workflows/builder.yaml) in our example app repository for a complete working example. Alternatively, use the [individual actions](https://github.com/home-assistant/builder?tab=readme-ov-file#example-workflow) in a more custom workflow as needed. | ||
|
|
||
|
|
||
| The new build workflow does not read `build.yaml`. You can remove the file from your repository. Its two commonly used sections should be migrated as follows: | ||
sairon marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| - **`build_from`** - replace the `build_from` key in `build.yaml` with a `FROM` statement in your `Dockerfile`: | ||
|
|
||
| ```dockerfile | ||
| FROM ghcr.io/home-assistant/base:latest | ||
| ``` | ||
|
|
||
| As the base images are now published as multi-platform manifests, there is usually no need to define per-arch base images anymore. The `build-image` action still supplies `BUILD_ARCH` as a build argument though, so you can use that in your `Dockerfile` if you need to use it in the template for the base image name. | ||
|
|
||
| - **`labels`** - move any custom Docker labels directly into your `Dockerfile` with a `LABEL` statement, with `io.hass.type="addon"` as a minimum to ensure the image is recognized as an app by Supervisor: | ||
|
|
||
| ```dockerfile | ||
| LABEL \ | ||
| io.hass.type="addon" \ | ||
| org.opencontainers.image.title="Your awesome app" \ | ||
| org.opencontainers.image.description="Description of your app." \ | ||
| org.opencontainers.image.source="https://github.com/your/repo" \ | ||
| org.opencontainers.image.licenses="Apache License 2.0" | ||
| ``` | ||
|
|
||
| - **`args`** - move custom build arguments into your `Dockerfile` as `ARG` definitions with default values: | ||
|
|
||
| ```dockerfile | ||
| ARG MY_BUILD_ARG="default-value" | ||
| ``` | ||
|
|
||
| Default values in `ARG` replace what was previously supplied via `build.yaml`'s `args` dictionary. They can still be overridden at build time with `--build-arg` if needed. | ||
|
|
||
sairon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ### Image naming | ||
|
|
||
| The preferred way to reference a published app image is now the **generic (multi-arch) name** without an architecture prefix: | ||
|
|
||
| ```yaml | ||
| # config.yaml | ||
| image: "ghcr.io/my-org/my-app" | ||
| ``` | ||
|
|
||
| The `{arch}` placeholder (e.g. `ghcr.io/my-org/{arch}-my-app`) is still supported as a compatibility fallback, but it's encouraged to use the generic name and let the manifest handle the platform resolution. | ||
|
|
||
| ### Local builds | ||
|
|
||
| After updating your `Dockerfile`, you can use `docker build` to build the app image directly - you can refer to [Local app testing](/docs/apps/testing) for more details. | ||
|
|
||
| ## Apps built locally by Supervisor | ||
|
|
||
| For backward compatibility, Supervisor still reads `build.yaml` file if it's present and populates the image build arguments with values read from this file. This will produce warnings and eventually be removed in the future, so it's recommended to migrate to the new Dockerfile-based approach as described above. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.