Add-ons and Docker architecture

Why the layer beneath Apps matters

Appendix A showed you where the app store is and how to install an app. That appendix teaches you how to use Apps; this chapter explains why they sometimes fail.

Consider a few situations you may encounter:

• You installed Home Assistant on a laptop, but there is no app store in the sidebar. You did nothing wrong: that installation type does not include it.
• You installed Zigbee2MQTT, but it will not start and its page says only “Stopped.” You do not know where to find the underlying error.
• You installed Node-RED and another web tool, but the second one refuses to start because both are trying to use the same port.
• You reinstalled the entire host, then discovered that every backup had been stored on the failed machine.

All four problems involve the same layer of knowledge: an app is a container, and containers have images, volumes, ports, and logs. By the end of this chapter, you will know where to start when any of these problems occurs.

The four installation types—and whether they include an app store

This is a major source of confusion for new users: not every Home Assistant installation includes the Apps (formerly add-ons) store. Its availability is determined by the installation type you chose; you cannot enable it later in Settings.

The practical conclusion is simple:

• Want the Apps store? Install HAOS. You can use Home Assistant Green or Yellow, flash the official image onto a Raspberry Pi, or install HAOS on a dedicated mini PC.
• Running Home Assistant Container—for example, with Docker on a Synology NAS? There is no store, and one cannot be added. Run services such as an MQTT broker or Node-RED in separate Docker containers. The capabilities are the same, but you must deploy and maintain those containers yourself.

An app is a Docker container managed by Supervisor

The official developer documentation is explicit: Apps—the feature formerly called add-ons—are built from container images published to a container registry, such as GitHub Container Registry or Docker Hub.

When you select “Install” in the store, the following happens:

1. Supervisor downloads the image

   It reads the app configuration to determine the registry, version, and image for your CPU architecture, such as arm64 or amd64. This is usually the longest step and the one most likely to fail if the network connection is interrupted.

2. Supervisor creates a container from the image

   Using the app configuration, it also determines which ports to expose, which folders to mount, and whether the container needs access to a USB device.

3. Supervisor integrates the management interface into Home Assistant

   This is why the app has Configuration and Log tabs inside the Home Assistant interface: you do not need to enter Docker commands yourself.

4. Supervisor keeps monitoring the container

   It handles starting, stopping, updating, automatic startup at boot, and restarts by the Watchdog. These functions correspond to the controls on the app page.

Supervisor is the manager. Home Assistant Core runs in one container, each app runs in its own container, and Supervisor manages their lifecycles. This also explains why Home Assistant Container has no store: that installation type does not include Supervisor; it runs only the Home Assistant container.

Docker in plain English: a restaurant kitchen

Docker terminology can sound intimidating, but each term describes a familiar role. Think of the system as a restaurant kitchen.

For Home Assistant Container, the official Docker Compose example brings these concepts together:

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: Etc/UTC

Here, image selects the application package. volumes maps host folders on the left to paths inside the container on the right. restart defines the restart policy, and TZ sets the time zone, which should match the setting discussed in Chapter 2. network_mode: host gives the container direct access to the host network, so port 8123 is available directly on that machine.

Hands-on: install an app and understand its controls

We will use File editor for this exercise because it is lightweight, low risk, and useful later.

1. Open the store

   In the lower-left corner, select Settings, then Apps (called Add-ons before 2026.2). Select Install app to open the store. In older releases, this button is labeled “ADD-ON STORE.”

   

   

2. Find File editor and install it

   File editor is in the Official section. Open it and select Install, then wait. The first installation must download a container image; three to five minutes is normal on a Raspberry Pi. A static screen does not necessarily mean that the installation has stalled.

3. Before starting it, review the four switches

   After installation, you will see Start on boot (run automatically after the host restarts), Watchdog (restart the app if it fails), Auto update (install new versions automatically), and Show in sidebar (add a shortcut to the sidebar). For File editor, enable all four.

4. Select “Start”

   The status should change from “Stopped” to “Running.” If it immediately returns to “Stopped,” startup failed. Continue to the next section and inspect the log.

5. Open it from the sidebar

   A File editor shortcut should now appear in the sidebar. Open it to see the /config folder—the persistent storage described in the previous section. Your configuration.yaml file is inside it.

6. Make and reverse a small edit

   This is a write-access test, not a configuration change. Change one character, save the file, and then restore the original text. Having completed this test, you will know that the editor can save changes when you need it.

What each tab on an app page does

Each app page contains several tabs. Their names vary slightly by release, but their functions are largely the same:

Troubleshoot with logs: a few markers are enough

A log can look impenetrable, but you do not need to understand every line. Follow these four steps:

1. Start at the bottom

   Logs are ordered chronologically from top to bottom, so the newest entries are at the bottom. The last five to ten lines often explain a startup failure. Ignore hundreds of earlier startup messages until you need them.

2. Look for these markers

   Search for ERROR, FATAL, Traceback, Permission denied, Address already in use, and No such file or directory. The relevant explanation is usually on or near that line. You can generally review WARNING entries after resolving the errors.

3. Search for the exact message

   Search for the line verbatim together with the app name—for example, “zigbee2mqtt Address already in use.” Do not paraphrase the error. An exact search is far more likely to find the relevant solution.

4. Capture a clean startup if the cause is still unclear

   Stop the app, refresh the log page, and select Start while watching the output. This captures one clean startup and is much easier to interpret than thousands of old messages.

Use this quick reference for common messages:

A tour of useful Apps

Do not install everything. Choose only what serves a specific need. In the Source column, Official means the app is included in the store by default; Community means that you must first add a third-party repository, as explained in the next section.

Add a third-party repository for Apps not in the default store

The store initially contains only the official selection. To install Apps such as Node-RED, Studio Code Server, or Zigbee2MQTT, first add their repository; the store will then display the Apps that repository provides.

1. Copy the repository URL

   Two commonly used repositories are the community Apps collection at https://github.com/hassio-addons/repository and the official Zigbee2MQTT repository at https://github.com/zigbee2mqtt/hassio-zigbee2mqtt.

2. Open the store

   Go to Settings → Apps, then select Install app.

3. Open “Repositories” from the three-dot menu

   On the store page, open the three-dot menu in the upper-right corner and select Repositories. Older releases may show a translated label for the same command.

4. Paste the URL, select Add, and refresh

   The store will gain one or more sections. If the new Apps do not appear, press Ctrl + F5 to force a refresh. If they are still missing, go to Settings → System → Logs and select Supervisor in the upper-right corner. Its log will reveal whether the repository URL is invalid.

Send backups off-device automatically

Chapter 9 explains how to create and schedule backups, how many to retain, and why local-only storage is inadequate. This section does not repeat those details.

This section expands on one point from Chapter 9: cloud backup destinations are now built in, so you do not need an app. This function once required a third-party add-on. The backup page now lets you select multiple Locations and send each backup to all of them automatically. The important differences—especially the restrictions—are summarized below.

Connect a cloud or network destination in three steps:

1. Connect the destination

   Home Assistant Cloud is already available if you have a Nabu Casa subscription. Otherwise, go to Settings → Devices & services → Add integration, add Google Drive or OneDrive, and follow the account authorization process. For a home NAS, use Settings → System → Storage instead; add network storage and make it available for backups.

2. Enable the destination on the Backups page

   Go to Settings → System → Backups and enable the new destination under Locations in the automatic-backup settings. Configure the schedule and retention as described in Chapter 9. Keep the local /backup destination enabled as well. A local copy restores quickly; the remote copy protects you if the entire host fails.

3. Run one backup manually and verify it at the destination

   Do not skip this step: an unverified backup is not a reliable backup. Open Google Drive or OneDrive and confirm that the file exists. If a Home Assistant Cloud upload exceeds the 5GB limit, return to the backup settings and exclude the media folder. It is often the largest component and offers the greatest reduction.

Managing resource use on lower-end hardware

Every app is a real, continuously running program that consumes CPU time, memory, and storage. A Raspberry Pi 4 with 2GB of memory or an older mini PC may slow down as Apps accumulate: pages load more slowly, automations are delayed, and updates fail. Home Assistant does not publish resource figures for every app, so the table below is a relative guide for prioritization, not a benchmark.

Follow these practical principles:

• Remove Apps you do not use; do not merely stop them. A stopped app still occupies storage.
• Install only one new app at a time. Observe it for a day or two before installing the next one, so that you can identify the cause if problems begin.
• Boot a Raspberry Pi from an SSD or other USB storage, not an SD card. Repeated writes are a leading cause of SD card failure, and database Apps write frequently.
• Check whether a built-in feature already meets the need. Installing Node-RED only to turn on a light at sunset is unnecessary; the built-in automation editor handles that task easily (see Chapter 8).

Common problems and how to diagnose them

1. The Apps store is missing

   First identify your installation type. Go to Settings → System → Repairs, then open the three-dot menu → System information. The Installation type field will identify OS or Container. Container and Core installations do not include the store by design; it cannot be enabled. To gain the store, reinstall with HAOS after creating and verifying a backup, then restore that backup. If you use HAOS but cannot find a particular app, such as Terminal & SSH, Advanced Mode may be disabled. Select your name in the lower-left corner to open your profile, then enable Advanced Mode.

2. An app is stuck installing or installation fails

   In roughly 90% of cases, the cause is a failed container-image download. Check these items in order: (1) Can Home Assistant reach the internet? (2) Is storage available under Settings → System → Storage? (3) Does the app publish an image for your CPU architecture? Less common Apps may provide only amd64 images and therefore cannot run on a Raspberry Pi; the error will usually say that no image was found. Retry once, because the first download may simply have been interrupted.

3. A port conflict prevents the second app from starting

   The log shows Address already in use or port is already allocated. On the affected app's Network tab, change the right-hand field to an unused host port—for example, from 1880 to 1881—then save and restart. Use the new port in the URL as well. If no external client needs to connect, leave the right-hand field blank instead; the conflict disappears because the port is not published on the host.

4. An app no longer starts after an update

   Read the last few lines of its log. The author may state that the configuration format changed and identify the option to update. If the required change is unclear, the fastest recovery is to restore the pre-update backup described in Chapter 9. This is why you should enable automatic backup before updates. Also check Settings → System → Repairs, where breaking changes may generate an explanatory notice.

   

5. Storage is full

   Full storage causes many apparently unrelated failures, and the log contains No space left on device. Clean up in this order: (1) Delete old backups, which are usually the largest files. (2) Remove—not merely stop—unused Apps. (3) Check the media and share folders for accumulated recordings. (4) If the database is too large, reduce the Recorder retention period. If the first three steps do not free enough space, move to a larger storage device.

6. An app keeps restarting

   If the status alternates between “Running” and “Stopped,” the Watchdog is probably restarting an app that continues to fail. Turn off Watchdog temporarily and let the app remain stopped so that you can read the complete error. Re-enable Watchdog after resolving the cause.

7. Zigbee2MQTT cannot find the USB adapter

   The log commonly shows No such file or directory. Go to Settings → System → Hardware, then select three-dot menu → All Hardware. Find the connected adapter and copy its path into the Zigbee2MQTT configuration. Do not copy a device path from an online tutorial; every host differs. Prefer the stable, long path beginning with /dev/serial/by-id/ instead of a short path such as /dev/ttyUSB0. A short path can change when devices are reconnected or the host restarts, while the by-id path identifies the adapter itself.

Frequently asked questions