diff --git a/blog/2020-10-29-supervisor-update.md b/blog/2020-10-29-supervisor-update.md index 55a2da8e109..e2898368831 100644 --- a/blog/2020-10-29-supervisor-update.md +++ b/blog/2020-10-29-supervisor-update.md @@ -5,6 +5,10 @@ authorTwitter: ludeeus title: "Upcoming changes to add-ons" --- +:::note +The builder action described in this post (`home-assistant/builder@master`) is a legacy workflow. It has since been replaced by dedicated composite actions. See the [builder migration post](/blog/2026/04/02/builder-migration) for the current recommended approach. +::: + ## GitHub Action You can now use our [builder][marketplace] as a [GitHub action][github_action]! :tada: diff --git a/blog/2026-04-02-builder-migration.md b/blog/2026-04-02-builder-migration.md new file mode 100644 index 00000000000..d427fce13dd --- /dev/null +++ b/blog/2026-04-02-builder-migration.md @@ -0,0 +1,75 @@ +--- +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 migrating all GitHub workflows and Dockerfiles for apps (formerly add-ons) as 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. The old builder also had unnecessary maintenance overhead. Today, what the builder does can be fully replaced with Docker BuildKit, which is natively supported on GitHub Actions runners and has built-in multi-arch support with QEMU emulation if needed. + +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 + +The migration has two parts: updating your Dockerfiles and updating your GitHub Actions workflows. + +### Update Dockerfiles + +The new build workflow doesn't use `build.yaml` anymore. Move the content into your `Dockerfile` as follows: + +- **`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: + + ```dockerfile + LABEL \ + 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" + ``` + + If you are creating a custom workflow, note that the legacy builder used to add the `io.hass.type`, `io.hass.name`, `io.hass.description`, and `io.hass.url` labels automatically. The new actions do not infer these values, so add them explicitly via the `labels` input of the `build-image` (or similar) action. + +- **`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. + +With the content of `build.yaml` migrated, you can delete the file from your repository. + +### Update GitHub Actions workflows + +Remove any workflow steps using `home-assistant/builder@master` and replace them with the new 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. + +### 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. diff --git a/docs/apps.md b/docs/apps.md index 723f98845e9..3417d315d00 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -22,7 +22,7 @@ Useful links: - [Home Assistant Supervisor](https://github.com/home-assistant/supervisor) - [Home Assistant Core Apps](https://github.com/home-assistant/addons) - [Home Assistant Docker base images](https://github.com/home-assistant/docker-base) -- [Home Assistant Builder](https://github.com/home-assistant/builder) +- [Home Assistant Builder actions](https://github.com/home-assistant/builder) - [Home Assistant community apps](https://github.com/hassio-addons) - [Home Assistant Operating System](https://github.com/home-assistant/operating-system) - [Home Assistant Docker images](https://github.com/home-assistant/docker) diff --git a/docs/apps/configuration.md b/docs/apps/configuration.md index c29e6fe7b5e..03ac7cb3631 100644 --- a/docs/apps/configuration.md +++ b/docs/apps/configuration.md @@ -9,7 +9,6 @@ addon_name/ translations/ en.yaml apparmor.txt - build.yaml CHANGELOG.md config.yaml DOCS.md @@ -21,7 +20,7 @@ addon_name/ ``` :::note -Translation files, `config` and `build` all support `.json`, `.yml` and `.yaml` as the file type. +Translation files and `config` support `.json`, `.yml` and `.yaml` as the file type. To keep it simple all examples use `.yaml` ::: @@ -58,7 +57,7 @@ then there will be a variable `TARGET` containing `beer` in the environment of y All apps (formerly known as add-ons) are based on the latest Alpine Linux image. Home Assistant will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need to run in a different timezone. `tzdata` Is is already added to our base images. ```dockerfile -ARG BUILD_FROM +ARG BUILD_FROM=ghcr.io/home-assistant/base:latest FROM $BUILD_FROM # Install requirements for app @@ -73,17 +72,15 @@ RUN chmod a+x /run.sh CMD [ "/run.sh" ] ``` -If you don't use local build on the device or our build script, make sure that the Dockerfile also has a set of labels that include: +If you are not using Home Assistant GitHub builder actions (see [Publishing your app](/docs/apps/publishing)), make sure that the Dockerfile also has a set of labels that include: ```dockerfile LABEL \ io.hass.version="VERSION" \ - io.hass.type="addon" \ - io.hass.arch="armhf|aarch64|i386|amd64" + io.hass.type="app" \ + io.hass.arch="aarch64|amd64" ``` -It is possible to use your own base image with `build.yaml` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`. You can also suffix the Dockerfile with the specific architecture to use a specific Dockerfile for a particular architecture, i.e. `Dockerfile.amd64`. - ### Build args We support the following build arguments by default: @@ -116,11 +113,11 @@ map: - type: homeassistant_config read_only: False path: /custom/config/path -image: repo/{arch}-my-custom-addon +image: ghcr.io/my-org/my-app ``` :::note -Avoid using `config.yaml` as filename in your app for anything other than the app configuration. The Supervisor does a recursively search for `config.yaml` in the app repository. +Avoid using `config.yaml` as filename in your app for anything other than the app configuration. The Supervisor does recursively search for `config.yaml` in the app repository. ::: ### Required configuration options @@ -131,7 +128,7 @@ Avoid using `config.yaml` as filename in your app for anything other than the ap | `version` | string | Version of the app. If you are using a docker image with the `image` option, this needs to match the tag of the image that will be used. | `slug` | string | Slug of the app. This needs to be unique in the scope of the [repository](/docs/apps/repository) that the app is published in and URI friendly. | | `description` | string | Description of the app. -| `arch` | list | A list of supported architectures: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`. +| `arch` | list | A list of supported architectures: `aarch64`, `amd64`. ### Optional configuration options @@ -172,8 +169,7 @@ Avoid using `config.yaml` as filename in your app for anything other than the ap | `legacy` | bool | `false` | If the Docker image has no `hass.io` labels, you can enable the legacy mode to use the config data. | `options` | dict | | Default options value of the app. | `schema` | dict | | Schema for options value of the app. It can be `false` to disable schema validation and options. -| `image` | string | | For use with Docker Hub and other container registries. This should be set to the name of the image only (E.g, `ghcr.io/home-assistant/{arch}-addon-example`). If you use this option, set the active docker tag using the `version` option. -| `codenotary` | string | | For use with Codenotary CAS. This is the E-Mail address used to verify your image with Codenotary (E.g, `example@home-assistant.io`). This should match the E-Mail address used as the signer in the [app's extended build options](#app-extended-build) +| `image` | string | | For use with container registries. Set this to the generic (multi-arch) image name, e.g. `ghcr.io/my-org/my-app`. The `{arch}` placeholder is still supported as a compatibility fallback for per-architecture image names (e.g. `ghcr.io/my-org/{arch}-my-app`). If you use this option, set the active Docker tag using the `version` option. | `timeout` | integer | 10 | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed. | `tmpfs` | bool | `false` | If this is set to `true`, the containers `/tmp` uses tmpfs, a memory file system. | `discovery` | list | | A list of services that this app provides for Home Assistant. @@ -269,30 +265,11 @@ We support: - `list(val1|val2|...)` - `device` / `device(filter)`: Device filter can be in the following format: `subsystem=TYPE` i.e. `subsystem=tty` for serial devices. -## App extended build - -Additional build options for an app are stored in `build.yaml`. This file will be read from our build systems. -This is only needed if you are not using the default images or need additional things. - -```yaml -build_from: - armhf: mycustom/base-image:latest -args: - my_build_arg: xy -``` - -| Key | Required | Description | -| --- | -------- | ----------- | -| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as the value. -| args | no | Allow additional Docker build arguments as a dictionary. -| labels | no | Allow additional Docker labels as a dictionary. -| codenotary | no | Enable container signature with codenotary CAS. -| codenotary.signer | no | Owner signer E-Mail address for this image. -| codenotary.base_image | no | Verify the base container image. If you use our official images, use `notary@home-assistant.io` +:::note -We provide a set of [base images][docker-base] which should cover a lot of needs. If you don't want to use the Alpine based version or need a specific image tag, feel free to pin this requirement for your build with the `build_from` option. +Previously, additional build options such as `build_from`, `args`, and `labels` were configured in a separate `build.yaml` file that was read by the legacy builder. This file is no longer used. Base images should be set directly with a `FROM` statement in your `Dockerfile`, labels with a `LABEL` statement, and custom build arguments with `ARG` definitions. See the [builder migration blog post](/blog/2026/04/02/builder-migration) for detailed migration instructions. -[docker-base]: https://github.com/home-assistant/docker-base +::: ## App translations diff --git a/docs/apps/presentation.md b/docs/apps/presentation.md index 9872490f3c5..251522f63dc 100644 --- a/docs/apps/presentation.md +++ b/docs/apps/presentation.md @@ -200,10 +200,8 @@ version: "1.0.0" slug: "nginx-ingress-example" description: "Ingress testing" arch: + - aarch64 - amd64 - - armhf - - armv7 - - i386 ingress: true ``` @@ -219,7 +217,6 @@ Each app starts with a base rating of 5, on a scale of 1 to 6. Depending on deci |---|---|---| | Use `ingress: true` in [`config.yaml`](/docs/apps/configuration#optional-configuration-options) | +2 | overrides `auth_api` rating | | Use `auth_api: true` in [`config.yaml`](/docs/apps/configuration#optional-configuration-options) | +1 | overridden by `ingress` | -| App is signed with [CodeNotary](https://cas.codenotary.com/)| +1|| | Use custom [`apparmor.txt`](/docs/apps/presentation#apparmor)| +1| Rating applied after installation | | Set `apparmor: false` in [`config.yaml`](/docs/apps/configuration#optional-configuration-options) | -1 | | | Use `privileged: NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_PTRACE`, `SYS_MODULE`, or `DAC_READ_SEARCH`, or `kernel_modules:` used in [`config.yaml`](/docs/apps/configuration#optional-configuration-options)| -1 | Rating applied only once if multiple are used. | diff --git a/docs/apps/publishing.md b/docs/apps/publishing.md index dc42076829c..4640184fbde 100644 --- a/docs/apps/publishing.md +++ b/docs/apps/publishing.md @@ -4,65 +4,47 @@ title: "Publishing your app" There are two different ways of publishing apps (formerly known as add-ons). One is to publish pre-built containers to a container registry and the other option is to have users build the containers locally on their Home Assistant instance. -#### Pre-built containers +## Pre-built containers -With pre-built containers, the developer is responsible for building the images for each architecture on their machine and pushing the results out to a container registry. This has a lot of advantages for the user who will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and has almost no chance of failure so it is the preferred method. +With pre-built containers, the developer is responsible for building the images for each architecture and pushing the results to a container registry. This has a lot of advantages for the user who will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and has almost no chance of failure, so it is the preferred method. -We have automated the process of building and publishing apps. See below for the instructions. +We have automated the process of building and publishing apps via GitHub Actions. See below for the instructions. -#### Locally build containers +## Locally built containers -With the Supervisor, it is possible to distribute apps that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your apps. This method includes installing and potentially compiling code. This means that installing such an app is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-built solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available. +With the Supervisor, it is possible to distribute apps that will be built on the user's machine. The advantage is that for you as a developer it is easy to test an idea and see if people are interested in your apps. This method includes installing and potentially compiling code. This means that installing such an app is slow and adds more wear and tear to users' SD cards/hard drives than the above-mentioned pre-built solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available. Use this option when you are playing with apps and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to a container registry as it greatly improves the user experience. In the future we will mark locally built apps in the app store to warn users. -## Build scripts to publish apps to a container registry +## Publishing apps to a container registry with GitHub Actions -All apps (formerly known as add-ons) are containers. Inside your app `config.yaml` you specify the container image that will be installed for your app: +The recommended way to build and publish multi-architecture app images is through GitHub Actions using the builder composite actions maintained by the Home Assistant project. These actions can be then used for a matrix of builds in an app repository. See the [builder workflow](https://github.com/home-assistant/apps-example/blob/main/.github/workflows/builder.yaml) in the example app repository for a complex example of building multiple apps, or the [example workflow](https://github.com/home-assistant/builder?tab=readme-ov-file#example-workflow) in the builder repository for a single app build. The builder actions are designed to be flexible and can be used in more complex workflows as needed. + +### Image naming + +Inside your app `config.yaml`, set the `image` field to the image name published in the container registry: ```yaml -... -image: "myhub/image-{arch}-addon-name" -... +image: "ghcr.io/my-org/my-app" ``` -You can use `{arch}` inside the image name to support multiple architectures with one (1) configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.yaml` to overwrite our default args. +The `{arch}` placeholder is still supported for backwards compatibility with per-architecture image publishing. When a multi-arch manifest is available, the generic name is the preferred public reference: -Home Assistant assumes that the default branch of your app repository matches the latest tag on the container registry. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the app to a container registry, you can merge this branch to master. - -## Custom apps +```yaml +# Preferred — resolves via the multi-arch manifest +image: "ghcr.io/my-org/my-app" -You need a Docker Hub account to make your own apps. You can build your container images with the Docker `build` command or use our [builder] to simplify the process. Pull our [Builder Docker engine][builder] and run one of the following commands. +# Compatibility fallback — still works if only arch-prefixed images exist +image: "ghcr.io/my-org/{arch}-my-app" +``` -For a git repository: +### Published images -```shell -docker run \ - --rm \ - --privileged \ - -v ~/.docker/config.json:/root/.docker/config.json:ro \ - ghcr.io/home-assistant/amd64-builder \ - --all \ - -t addon-folder \ - -r https://github.com/xy/addons \ - -b branchname -``` +After a successful run, two types of image references are available: -For a local repository: - -```shell -docker run \ - --rm \ - --privileged \ - -v ~/.docker/config.json:/root/.docker/config.json:ro \ - -v /my_addon:/data \ - ghcr.io/home-assistant/amd64-builder \ - --all \ - -t /data -``` +- **Per-architecture images** (e.g. `ghcr.io/my-org/aarch64-my-app:1.0.0`) — pushed by the `build-image` action. +- **Generic manifest image** (e.g. `ghcr.io/my-org/my-app:1.0.0`) — pushed by the `publish-multi-arch-manifest` action; this is the preferred reference to use in `config.yaml` and to share with users. -:::tip -If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: `error creating aufs mount to /var/lib/docker/aufs/mnt/-init: invalid argument`. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: `"storage-driver" : "aufs"` or map the docker socket into container. -::: +### Example app repository -[builder]: https://github.com/home-assistant/builder +See the [Home Assistant example app repository](https://github.com/home-assistant/apps-example) for a complete, up-to-date working example. diff --git a/docs/apps/security.md b/docs/apps/security.md index 6ffe04f61be..7f254058678 100644 --- a/docs/apps/security.md +++ b/docs/apps/security.md @@ -18,10 +18,6 @@ For access to the Supervisor API you need to define a role or run in default mod | `manager` | Is for Apps that run CLIs and need extended rights | | `admin` | Have access to every API call. That is the only one they can disable/enable the App protection mode | -## Codenotary CAS - -You can sign your images and also verify our base image which you build from to provide a full chain of trust. This feature is supported by our [Builder](https://github.com/home-assistant/builder) and the [build config](/docs/apps/configuration#app-extended-build). To enable this feature on the Supervisor for your app, you simply need to add your email address to the app configuration `codenotary`. - ## Protection By default, all apps run in protection-enabled mode. This mode prevents the app from getting any rights on the system. If an app requires more rights, you can disable this protection via the API app options for that app. But be careful, an app with disabled protection can destroy your system! @@ -34,7 +30,7 @@ As a developer, follow the following best practices to make your app secure: - Create an AppArmor profile - Map folders read only if you don't need write access - If you need any API access, make sure that you do not grant permission that aren't needed -- Sign the image with [Codenotary CAS](https://cas.codenotary.com/) +- Sign published images (the supported [publishing workflow](/docs/apps/publishing) can sign images with Cosign) ## Use Home Assistant user backend diff --git a/docs/apps/testing.md b/docs/apps/testing.md index 325a5de600e..b3ea852e189 100644 --- a/docs/apps/testing.md +++ b/docs/apps/testing.md @@ -20,43 +20,23 @@ Right now apps will work with images that are stored on Docker Hub (using `image ## Local build -If you don't want to use the devcontainer environment, you can still build apps locally with Docker. The recommended method is to use the [official build tool][hassio-builder] to create the Docker images. - -Assuming that your addon is in the folder `/path/to/addon` and your Docker socket is at `/var/run/docker.sock`, you can build the addon for all supported architectures by running the following: - -```shell -docker run \ - --rm \ - -it \ - --name builder \ - --privileged \ - -v /path/to/addon:/data \ - -v /var/run/docker.sock:/var/run/docker.sock:ro \ - ghcr.io/home-assistant/amd64-builder \ - -t /data \ - --all \ - --test \ - -i my-test-addon-{arch} \ - -d local -``` - -If you don't want to use the official build tool, you can still build with standalone Docker. If you use `FROM $BUILD_FROM` you'll need to set a base image with build args. Normally you can use following base images: - -- armhf: `ghcr.io/home-assistant/armhf-base:latest` -- aarch64: `ghcr.io/home-assistant/aarch64-base:latest` -- amd64: `ghcr.io/home-assistant/amd64-base:latest` -- i386: `ghcr.io/home-assistant/i386-base:latest` +If you don't want to use the devcontainer environment, you can build apps locally with standalone Docker. This is useful for quick single-architecture checks on the host you are currently working on. Use `docker` from the directory containing the app files to build the test addon: ```shell docker build \ - --build-arg BUILD_FROM="ghcr.io/home-assistant/amd64-base:latest" \ - -t local/my-test-addon \ + -t local/my-test-app \ . ``` -[hassio-builder]: https://github.com/home-assistant/builder +For a multi-platform build or cross-compilation, you can use the `--platform` flag with the appropriate target platform (e.g. `--platform linux/arm64` to build `aarch64` image in QEMU on an AMD64 host). See the official Docker documentation on [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) for more details. + +:::note + +The architecture used in `--platform` option is not the same as the one used in Home Assistant. While `amd64` in Home Assistant corresponds to `--platform linux/amd64`, `aarch64` in Home Assistant corresponds to `--platform linux/arm64` in Docker. + +::: ## Local run @@ -69,7 +49,7 @@ docker run \ --rm \ -v /tmp/my_test_data:/data \ -p PORT_STUFF_IF_NEEDED \ - local/my-test-addon + local/my-test-app ``` ## Logs diff --git a/docs/apps/tutorial.md b/docs/apps/tutorial.md index f5363082d24..cc5661bf765 100644 --- a/docs/apps/tutorial.md +++ b/docs/apps/tutorial.md @@ -54,9 +54,6 @@ init: false arch: - aarch64 - amd64 - - armhf - - armv7 - - i386 ``` ### The `run.sh` file @@ -148,9 +145,6 @@ init: false arch: - aarch64 - amd64 - - armhf - - armv7 - - i386 startup: services ports: 8000/tcp: 8000 diff --git a/docs/supervisor/development.md b/docs/supervisor/development.md index b636a20caef..82ffc720be0 100644 --- a/docs/supervisor/development.md +++ b/docs/supervisor/development.md @@ -24,45 +24,51 @@ When the initializing is complete you can access the Home Assistant frontend on ### Testing on a remote system -For this you first need to create an account at [Docker Hub](https://hub.docker.com/). - 1. Access the remote system with SSH or with direct console access. 2. Check the architecture on the machine with `ha info` or just `info` if it's Home Assistant OS. -3. On your development machine use our [builder](https://github.com/home-assistant/builder) to build and publish your Supervisor image. +3. On your development machine, build and push your Supervisor image to a container registry. Using GitHub Container Registry as an example (adjust `YOUR_GH_USERNAME` and the architecture to match what you found in step 2): -Example: +```bash +docker build \ + --platform linux/arm64 \ + --tag ghcr.io/YOUR_GH_USERNAME/aarch64-hassio-supervisor:latest \ + --push \ + . +``` :::note All examples will have values you need to adjust. -- Adjust `aarch64` with the architecture you found in step 2. -- Adjust `awesome-user` to match your Docker Hub username. -- Adjust `secret-password` to match your Docker Hub password or publish token. +- Adjust `linux/arm64` and `aarch64` with the architecture you found in step 2. +- Adjust `YOUR_GH_USERNAME` to match your GitHub username or organization. +- To push an image to GitHub Container Registry like in the example above, you need to authenticate using a personal access token with appropriate scopes. See the [GitHub Container Registry documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) for more details. + +::: + +:::note + +The architecture used in `--platform` option is not the same as the one used in Home Assistant. While `amd64` in Home Assistant corresponds to `--platform linux/amd64`, `aarch64` in Home Assistant corresponds to `--platform linux/arm64` in Docker. ::: +4. On your remote system change the channel to `dev` with `ha supervisor --channel dev` or just `supervisor --channel dev` if it's Home Assistant OS. +5. Pull down your Supervisor image: + ```bash -docker run --rm \ - --privileged \ - -v /run/docker.sock:/run/docker.sock \ - -v "$(pwd):/data" \ - ghcr.io/home-assistant/amd64-builder:dev \ - --generic latest \ - --target /data \ - --aarch64 \ - --docker-hub awesome-user \ - --docker-user awesome-user \ - --docker-password secret-password \ - --no-cache +docker pull ghcr.io/YOUR_GH_USERNAME/aarch64-hassio-supervisor:latest ``` -4. On your remote system change the channel to `dev` with `ha supervisor --channel dev` or just `supervisor --channel dev` if it's Home Assistant OS. -5. Pull down your Supervisor image with `docker pull awesome-user/aarch64-hassio-supervisor:latest` -6. Tag your Supervisor image as `homeassistant/aarch64-hassio-supervisor:latest` +:::note + +Docker images uploaded to GHCR are by default private. To download them, you will either need to authenticate using a personal access token on the remote system as well or [change the visibility](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#configuring-visibility-of-packages-for-your-personal-account) of the package on GitHub. + +::: + +6. Tag your Supervisor image as the expected local name: ```bash -docker tag awesome-user/aarch64-hassio-supervisor:latest homeassistant/aarch64-hassio-supervisor:latest +docker tag ghcr.io/YOUR_GH_USERNAME/aarch64-hassio-supervisor:latest ghcr.io/home-assistant/aarch64-hassio-supervisor:latest ``` 7. Restart the `hassio-supervisor` service with `systemctl restart hassos-supervisor`