ha-addon

Home Assistant アドオン開発

Docker、Supervisor との統合、マルチアーキテクチャ対応を活用して Home Assistant アドオンを構築、設定、公開するための専門的なガイダンスです。

始める前に

このスキルは、Home Assistant アドオン開発でよくあるミスを防ぎます。

問題	症状	解決策
権限エラー	Supervisor API 呼び出しで Permission denied が発生する	正しい SUPERVISOR_TOKEN と API エンドポイントを使用します
設定の検証	アドオンが読み込まれない	公開前に config.yaml のスキーマを検証します
Docker ベースイメージのエラー	実行環境で依存関係が不足している	Home Assistant 公式ベースイメージ（ghcr.io/home-assistant）を使用します
Ingress の設定ミス	HA 経由で Web UI にアクセスできない	nginx リバースプロキシを正しく設定します
マルチアーキテクチャビルドの失敗	アドオンが 1 つのアーキテクチャでしか動作しない	アーキテクチャマトリックスを含む build.yaml を設定します

クイックスタート：アドオンをゼロから作成する

ステップ 1：アドオンのディレクトリ構造を作成する

mkdir -p my-addon/{rootfs,rootfs/etc/s6-overlay/s6-rc.d/service-name}
cd my-addon

重要な理由： Home Assistant では、特定のディレクトリ構成が必要です。rootfs/ には、Docker イメージにパッケージ化される実際のアプリケーションファイルを格納します。

ステップ 2：config.yaml を作成する

---
name: My Custom Add-On
description: My awesome Home Assistant add-on
version: 1.0.0
slug: my-addon
image: ghcr.io/home-assistant/{arch}-addon-my-addon
arch:
  - amd64
  - armv7
  - aarch64
ports:
  8080/tcp: null
options:
  debug: false
schema:
  debug: bool
permissions:
  - homeassistant  # Read/write Home Assistant core data

重要な理由： これはアドオンのマニフェストです。slug は内部識別子となり、設定の保存先を決定します。

ステップ 3：Dockerfile を作成する

FROM ghcr.io/home-assistant/amd64-base:latest

# Install dependencies
RUN apk add --no-cache python3 py3-pip

# Copy application
COPY rootfs /

# Set working directory
WORKDIR /app

# Install Python packages if needed
RUN if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# Run using S6 overlay
CMD ["/init"]

重要な理由： Home Assistant ベースイメージを使用すると、重要な実行時コンポーネント（S6 overlay、bashio ヘルパー、Supervisor 統合）が含まれます。

ステップ 4：S6 サービススクリプトを作成する

rootfs/etc/s6-overlay/s6-rc.d/service-name/run を作成します。

#!/command/execlineb -P
foreground { echo "Starting my add-on..." }
/app/my-service

実行可能にします。

chmod +x rootfs/etc/s6-overlay/s6-rc.d/service-name/run

重要な理由： S6 overlay は Home Assistant の init システムです。サービスの起動、ログ記録、正常なシャットダウンを管理します。

重要なルール

✅ 必ず行うこと

• ✅ Home Assistant 公式ベースイメージ（ghcr.io/home-assistant/{arch}-base）を使用します
• ✅ config.yaml にサポート対象のすべてのアーキテクチャ（amd64、armv7、aarch64）を含めます
• ✅ 一般的な処理には bashio ヘルパー関数（bashio::log::info、bashio::addon::option）を使用します
• ✅ リリース前に config.yaml のスキーマを検証します
• ✅ スキーマセクションに設定オプションを記載します
• ✅ デバッグ用にログへ addon_uuid を含めます

❌ 絶対にしないこと

• ❌ パスをハードコードせず、bashio を使って設定ディレクトリ（/data/）を取得します
• ❌ 絶対に必要な場合を除き、サービスを root として実行しません（Dockerfile で USER を設定します）
• ❌ SUPERVISOR_TOKEN なしで Supervisor API を呼び出しません
• ❌ SIGTERM シグナルを無視せず、正常なシャットダウンを実装します
• ❌ 1 つのアーキテクチャだけを想定せず、イメージ名に {arch} プレースホルダーを使用します
• ❌ /data/ 以外にデータを保存しません。Home Assistant はそのデータを保持しません

よくある間違い

❌ 誤り：パスのハードコード

#!/bin/bash
CONFIG_PATH="/config/my-addon"

✅ 正しい方法：bashio を使った設定

#!/command/execlineb -P
CONFIG_PATH=${"$(bashio::addon::config_path)"}

理由： bashio はパスの解決を処理し、どの Home Assistant インストール環境でもアドオンが動作するようにします。

設定リファレンス

config.yaml の構造

---
name: String                          # Display name
description: String                   # Short description
version: String                       # Semantic version (1.0.0)
slug: String                          # URL-safe identifier
image: String                         # Docker image URL with {arch} placeholder
arch:
  - amd64|armv7|aarch64|armhf|i386    # Supported architectures
ports:
  8080/tcp: null                      # TCP port (null=internal only, number=external)
  53/udp: 53                          # UDP with external port mapping
devices:
  - /dev/ttyACM0                      # Device access
services:
  - mysql                             # Depends on other service
options:
  debug: false                        # User configuration options
  log_level: info
schema:
  debug: bool                         # Configuration validation schema
  log_level:
    - debug
    - info
    - warning
    - error
permissions:
  - homeassistant                     # Read/write HA config
  - hassio                            # Full supervisor API access
  - admin                             # Broad system access
  - backup                            # Backup/restore operations
environment:
  NODE_ENV: production
webui: http://[HOST]:[PORT:8080]     # Web UI URL pattern
ingress: true                         # Enable ingress proxy
ingress_port: 8080                    # Internal port for ingress
ingress_entry: /                      # URL path for ingress entry

主な設定：

• slug：内部および Supervisor API 呼び出しで使用されます
• arch：サポートするすべてのアーキテクチャを列挙します。指定しないとビルドに失敗します
• image：動的ビルドには {arch} プレースホルダーを使用する必要があります
• options：ユーザーが設定可能な項目です
• permissions：Supervisor API のアクセスレベルを制御します
• ingress：Web UI 用のリバースプロキシを有効にします

よく使われるパターン

bashio を使ったログ記録

#!/command/execlineb -P
foreground { bashio::log::info "Add-on started" }
foreground { bashio::log::warning "Low disk space" }
foreground { bashio::log::error "Failed to connect" }

設定オプションへのアクセス

#!/command/execlineb -P
define DEBUG "$(bashio::addon::option 'debug')"
define LOG_LEVEL "$(bashio::addon::option 'log_level')"
if { test "${DEBUG}" = "true" }
  bashio::log::debug "Debug mode enabled"

Supervisor API 通信

#!/bin/bash
# Get addon info
curl -X GET \
  -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  http://supervisor/addons/self/info | jq .

# Send notification
curl -X POST \
  -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Warning message"}' \
  http://supervisor/notifications/create

マルチアーキテクチャ Docker ビルド

build.yaml を作成します。

build_from:
  amd64: ghcr.io/home-assistant/amd64-base:latest
  armv7: ghcr.io/home-assistant/armv7-base:latest
  aarch64: ghcr.io/home-assistant/aarch64-base:latest
  armhf: ghcr.io/home-assistant/armhf-base:latest
codenotary: your-notary-id  # Optional code signing

Web UI 用の Ingress 設定

ingress: true
ingress_port: 8080
ingress_entry: /
# Optional ingress_stream for streaming endpoints

アプリ内では、正しいリバースプロキシヘッダーを使用します。

# nginx configuration in your app
location / {
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header Host $host;
  proxy_pass http://localhost:8080;
}

既知の問題の防止

問題	根本原因	解決策
アドオンが起動しない	S6 サービスファイルがない	run 実行ファイルを含む /etc/s6-overlay/s6-rc.d/service-name/ を作成します
Supervisor API が 401 を返す	SUPERVISOR_TOKEN が無効	Home Assistant によってトークンが設定されていることを確認します（ログを addon_uuid で確認）
設定が保持されない	/data/ 以外に保存している	永続化には必ず bashio::addon::config_path または /data/ を使用します
ポートがすでに使用されている	複数のサービスが同じポートを使用している	設定を確認します。各サービスには一意のポートが必要です
アーキテクチャが一致しない	{arch} プレースホルダーを使用していない	イメージフィールドで正確なプレースホルダーを使用します：ghcr.io/home-assistant/{arch}-base
「Unknown architecture」エラーでビルドに失敗する	config.yaml に未対応のアーキテクチャが記載されている	次のものだけを使用します：amd64、armv7、aarch64、armhf、i386

Supervisor API エンドポイント

# Authentication: Pass SUPERVISOR_TOKEN header
# Base URL: http://supervisor

GET /addons/self/info            # Get current add-on details
POST /addons/self/restart        # Restart this add-on
GET /addons/installed            # List installed add-ons
GET /info                        # System information
POST /notifications/create       # Send notification to user
GET /config/homeassistant        # Read Home Assistant config

# Example with bashio
bashio::addon::self_info         # Helper function for self info

依存関係

必須

パッケージ	バージョン	用途
Home Assistant	2024.1+	アドオンプラットフォームと Supervisor
Docker	最新	コンテナランタイム
S6 Overlay	3.x	初期化システム（ベースイメージに含まれています）

任意

パッケージ	バージョン	用途
bashio	最新	ヘルパー関数（ベースイメージに含まれています）
python3	3.9+	Python ベースのアドオン
nodejs	18+	Node.js ベースのアドオン

公式ドキュメント

• Home Assistant アドオン開発
• アドオン設定リファレンス
• Supervisor 開発
• bashio ヘルパー関数
• S6 Overlay ドキュメント

トラブルシューティング

アドオンが起動しない

症状： アドオンが「Not running」または「Unknown」と表示される

解決策：

# Check logs
docker logs addon_name_latest  # Or use HA UI: Settings > System > Logs

# Common causes:
# 1. Invalid config.yaml syntax
# 2. Missing S6 service files
# 3. Dockerfile can't find base image
# 4. Permission denied on rootfs files

Supervisor API が 401 を返す

症状： API 呼び出しが「Unauthorized」で失敗する

解決策：

# Verify SUPERVISOR_TOKEN is set
echo $SUPERVISOR_TOKEN

# Check add-on logs for token errors
# Token is automatically injected by Home Assistant

# Verify permissions in config.yaml
# If calling hassio endpoints, add: permissions: [hassio]

設定が保存されない

症状： 再起動後にオプションが失われる

解決策：

# Always save to /data/ or use bashio
CONFIG_PATH="$(bashio::addon::config_path)"  # Returns /data/
echo "my_value=123" > "${CONFIG_PATH}/settings.json"

# Verify /data/ exists and is writable
ls -la /data/

Ingress の Web UI にアクセスできない

症状： Ingress URL が 502 または空白のページを返す

解決策：

# 1. Verify service is listening on correct port
netstat -tlnp | grep 8080

# 2. Check reverse proxy headers in app config
# X-Forwarded-For, X-Forwarded-Proto must be set

# 3. Verify ingress settings in config.yaml
ingress: true
ingress_port: 8080
ingress_entry: /

アーキテクチャエラーでビルドに失敗する

症状： 「Unknown architecture」または「Image not found」

解決策：

# Check config.yaml has valid arch values
arch:
  - amd64      # x86 64-bit
  - armv7      # 32-bit ARM (Pi 2/3)
  - aarch64    # 64-bit ARM (Pi 4+)
  - armhf      # 32-bit ARM (older devices)
  - i386       # 32-bit x86 (rare)

# Dockerfile must use {arch} placeholder
FROM ghcr.io/home-assistant/{arch}-base:latest

セットアップチェックリスト

アドオンを公開する前に、次の項目を確認してください：

• config.yaml の YAML 構文が有効である（オンラインの YAML バリデーターを使用）
• 記載されているすべてのアーキテクチャがサポートされている（amd64、armv7、aarch64、armhf、i386）
• Dockerfile が Home Assistant の公式ベースイメージを使用している
• S6 サービスファイルが存在し、実行可能である（chmod +x）
• すべての設定オプションがスキーマに記載されている
• ハードコードされたパスがない（bashio ヘルパーを使用）
• permissions フィールドに必要な Supervisor API アクセスが記載されている
• 少なくとも amd64 と ARM アーキテクチャでテスト済みである
• ログに bashio::log 関数を使用している
• SIGTERM による正常なシャットダウンが実装されている
• すべての永続データに /data/ を使用している
• Web UI を提供する場合、Ingress が動作している
• README にインストールと使用方法の手順が記載されている

リポジトリの作成

複数のアドオンを公開するには：

1. リポジトリ構成を作成する

mkdir my-addon-repo
cd my-addon-repo

2. repository.yaml を作成する

---
name: My Add-On Repository
url: https://github.com/username/my-addon-repo
maintainer: Your Name <[email protected]>

3. アドオンを追加する

my-addon-repo/
├── repository.yaml
├── my-addon-1/
│   ├── config.yaml
│   ├── Dockerfile
│   └── rootfs/
└── my-addon-2/
    ├── config.yaml
    ├── Dockerfile
    └── rootfs/

4. GitHub にプッシュする

Home Assistant にリポジトリの URL を追加すると、アドオンを見つけられるようになります。

上級：GitHub Container Registry への公開

プライベートリポジトリまたはマルチアーキテクチャビルドの場合：

# Build and push for all architectures
docker buildx build \
  --platform linux/amd64,linux/arm/v7,linux/arm64/v8 \
  -t ghcr.io/username/my-addon:1.0.0 \
  --push .

関連スキル

• docker-configs - Docker の基礎とベストプラクティス
• esphome-config-helper - IoT デバイス統合に関する関連パターン
• home-assistant-automation - Home Assistant の自動化とスクリプト