Home Assistant w Dockerze – instalacja, konfiguracja i zarządzanie kontenerem

Home Assistanta można wygodnie uruchomić w kontenerze Dockera, co upraszcza instalację, aktualizowanie oraz zarządzanie środowiskiem automatyki domowej.

Wprowadzenie – Home Assistant jako kontener Dockera

Home Assistant to popularna platforma open source do automatyki domowej. Wariant Home Assistant Container jest dostarczany jako standardowy obraz kontenera, który można uruchomić na serwerze z Dockerem.

Konteneryzacja zapewnia izolację środowiska, ułatwia migrację między serwerami i pozwala aktualizować aplikację przez podmianę obrazu. Cały inteligentny dom może działać jako stos kilku kontenerów obejmujący między innymi Home Assistanta, broker MQTT, Zigbee2MQTT i serwer proxy HTTPS.

Home Assistant Container nie zawiera Supervisora ani sklepu z dodatkami znanego z Home Assistant OS. Usługi dodatkowe, takie jak broker MQTT, należy instalować, konfigurować i aktualizować jako osobne kontenery.

Wymagania wstępne

Do uruchomienia Home Assistanta potrzebne jest urządzenie z systemem Linux, serwer NAS, na przykład Synology, albo inna maszyna obsługująca Dockera. Hostowi warto przypisać stały adres IP, aby panel Home Assistanta był zawsze dostępny pod tym samym adresem.

W systemach takich jak Arch Linux należy uruchomić i włączyć usługę docker.service. Użytkownika można również dodać do grupy docker, aby korzystać z Dockera bez polecenia sudo. Trzeba jednak pamiętać, że członkostwo w grupie docker zapewnia uprawnienia zbliżone do uprawnień administratora systemu.

Warto także przygotować katalog, na przykład /docker-data lub /opt/homeassistant, przeznaczony na dane kontenerów i pliki compose.yml.

Plan struktury środowiska

Dane Home Assistanta muszą być przechowywane w trwałym katalogu mapowanym do ścieżki /config wewnątrz kontenera. W zależności od platformy można zastosować następujące lokalizacje:

• Serwer x86-64 – /opt/homeassistant/config;
• Synology NAS – /volume1/docker/homeassistant/config;
• Katalog domowy użytkownika – ~/homeassistant/config.

W bardziej rozbudowanych instalacjach warto utworzyć osobne katalogi dla Home Assistanta, Mosquitto, Zigbee2MQTT, Nginx Proxy Managera oraz narzędzi do tworzenia kopii zapasowych. Taka struktura ułatwia aktualizowanie usług, migrację środowiska i odtwarzanie danych po awarii.

Instalacja Dockera

W Debianie i Ubuntu Docker może zostać zainstalowany z oficjalnego repozytorium za pomocą pakietów docker-ce, docker-ce-cli oraz containerd.io. Pakiet docker-compose-plugin udostępnia natomiast polecenie docker compose.

W Arch Linux można skorzystać z pakietów dostępnych w repozytoriach dystrybucji, a następnie uruchomić usługę Dockera, utworzyć katalog projektu i przygotować plik compose.yml.

Na urządzeniach Synology NAS Docker jest dostępny za pośrednictwem aplikacji Container Manager, która umożliwia pobieranie obrazów i tworzenie kontenerów z poziomu interfejsu graficznego.

Podstawowy kontener Home Assistanta z użyciem docker run

Home Assistanta można uruchomić za pomocą pojedynczego polecenia docker run. Przykładowa komenda dla serwera z systemem Linux wygląda następująco:

docker run -d \
--name homeassistant \
--privileged \
--restart unless-stopped \
-e TZ=Europe/Warsaw \
-v /opt/homeassistant/config:/config \
-v /run/dbus:/run/dbus:ro \
--network host \
ghcr.io/home-assistant/home-assistant:stable

ghcr.io/home-assistant/home-assistant:stable to oficjalny obraz wariantu Home Assistant Container. Poszczególne parametry odpowiadają za następujące ustawienia:

• Nazwa kontenera – parametr --name homeassistant ułatwia późniejsze zarządzanie usługą;
• Uprawnienia – opcja --privileged zapewnia szeroki dostęp do zasobów hosta, dlatego należy stosować ją wyłącznie wtedy, gdy wymagają tego urządzenia fizyczne lub konkretne integracje;
• Automatyczny restart – ustawienie --restart unless-stopped ponownie uruchamia kontener po restarcie hosta, o ile nie został wcześniej zatrzymany ręcznie;
• Strefa czasowa – zmienna TZ=Europe/Warsaw zapewnia prawidłowe działanie harmonogramów i automatyzacji zależnych od czasu;
• Wolumen konfiguracji – mapowanie /opt/homeassistant/config:/config zapisuje konfigurację, integracje i bazę danych poza kontenerem;
• Dostęp do D-Bus – montowanie /run/dbus:/run/dbus:ro umożliwia korzystanie z integracji wymagających komunikacji z magistralą D-Bus hosta;
• Sieć hosta – tryb --network host ułatwia automatyczne wykrywanie urządzeń za pomocą protokołów takich jak mDNS i SSDP.

Na Synology NAS można zastosować podobną konfigurację, zmieniając ścieżkę wolumenu na przykład na /volume1/docker/homeassistant/config:/config.

Uruchomienie kontenera przez Docker Compose

Docker Compose jest wygodniejszy od pojedynczego polecenia docker run, szczególnie gdy środowisko obejmuje kilka powiązanych usług. Podstawowa procedura składa się z następujących kroków:

1. utwórz katalog projektu, na przykład ~/homeassistant lub /opt/homeassistant;
2. przejdź do tego katalogu i utwórz plik compose.yml;
3. wklej definicję usługi homeassistant i dostosuj ścieżki;
4. uruchom stos poleceniem docker compose up -d.

Podstawowy plik compose.yml może wyglądać następująco:

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

Kluczowe znaczenie mają prawidłowe ścieżki wolumenów, właściwa strefa czasowa i odpowiednio dobrany tryb sieciowy. Ścieżkę do katalogu z danymi można zapisać w pliku .env, a następnie wykorzystać jako zmienną w konfiguracji Compose. Pozwala to zmienić lokalizację danych bez edytowania całej definicji usługi.

Dostępne są również alternatywne obrazy, takie jak linuxserver/homeassistant, obsługujące dodatkowe parametry, w tym PUID, PGID oraz mapowanie urządzeń. W większości instalacji zalecany jest jednak oficjalny obraz Home Assistanta.

Zarządzanie stosem w Portainerze i interfejsie graficznym

Kontenerami można zarządzać za pomocą Portainera zamiast terminala. Typowa konfiguracja obejmuje następujące działania:

• Przygotowanie danych – utworzenie katalogu, na przykład /docker-data, wraz z odpowiednimi podkatalogami i plikami Compose;
• Utworzenie stosu – dodanie w Portainerze nowego stosu, na przykład home_automation, i wklejenie definicji usług Home Assistant, MQTT oraz Zigbee2MQTT;
• Ustawienie parametrów – skonfigurowanie zmiennych środowiskowych, takich jak TZ=Europe/Warsaw, oraz ścieżek do katalogów z danymi;
• Uruchomienie usług – wdrożenie wszystkich kontenerów za pomocą funkcji Deploy the stack.

Podobne możliwości oferuje Dockge, czyli panel przeznaczony do zarządzania wieloma stosami Docker Compose. Narzędzia tego typu zazwyczaj korzystają z gniazda /var/run/docker.sock. Dostęp do ich interfejsu powinien być odpowiednio zabezpieczony, ponieważ przejęcie panelu może umożliwić kontrolę nad hostem Dockera.

Pierwsze uruchomienie i konfiguracja Home Assistanta

Po uruchomieniu kontenera należy odczekać kilka minut, aż Home Assistant zakończy inicjalizację. Interfejs WWW będzie domyślnie dostępny pod adresem http://ADRES_HOSTA:8123, gdzie ADRES_HOSTA oznacza adres IP serwera lub urządzenia NAS.

Na Synology NAS pierwsze uruchomienie może potrwać od dwóch do trzech minut. Po tym czasie kreator konfiguracji powinien być dostępny pod adresem http://ADRES_NAS:8123.

Podczas pierwszego uruchomienia Home Assistant przeprowadzi użytkownika przez najważniejsze etapy konfiguracji:

• utworzenie konta administratora,
• ustawienie lokalizacji domu, strefy czasowej i jednostek miar,
• sprawdzenie urządzeń automatycznie wykrytych w sieci.

Wszystkie ustawienia są zapisywane w katalogu /config zmapowanym z systemu hosta.

Podstawowe zarządzanie kontenerem

Do codziennego zarządzania instalacją wystarczy kilka poleceń Dockera:

• Zatrzymanie kontenera – docker stop homeassistant;
• Uruchomienie kontenera – docker start homeassistant;
• Ponowne uruchomienie – docker restart homeassistant;
• Podgląd logów – docker logs homeassistant lub docker logs -f homeassistant;
• Sprawdzenie statusu – docker ps lub docker ps -a.

W przypadku Docker Compose pobranie nowego obrazu i ponowne utworzenie usługi zazwyczaj wymaga wykonania poleceń docker compose pull oraz docker compose up -d.

Działanie kontenera można dodatkowo kontrolować za pomocą mechanizmu healthcheck. Test może sprawdzać dostępność interfejsu na porcie 8123, ale wymaga obecności odpowiedniego narzędzia, na przykład curl lub wget, wewnątrz obrazu kontenera.

Aktualizowanie Home Assistanta w Dockerze

Aktualizacja Home Assistanta polega na pobraniu nowszego obrazu i ponownym utworzeniu kontenera. W instalacji uruchamianej przez docker run należy wykonać następujące czynności:

1. utwórz kopię zapasową katalogu /config;
2. zatrzymaj dotychczasowy kontener poleceniem docker stop homeassistant;
3. usuń kontener poleceniem docker rm homeassistant;
4. pobierz aktualny obraz poleceniem docker pull ghcr.io/home-assistant/home-assistant:stable;
5. uruchom nowy kontener z tym samym mapowaniem katalogu /config.

W przypadku Docker Compose aktualizacja jest krótsza i zwykle obejmuje następujące kroki:

1. zmień tag obrazu w pliku compose.yml, jeśli korzystasz z konkretnej wersji;
2. pobierz obraz poleceniem docker compose pull;
3. odtwórz usługę poleceniem docker compose up -d.

Ponieważ konfiguracja jest przechowywana poza kontenerem w katalogu /config, wymiana obrazu nie powinna usuwać ustawień ani historii. Przed większą aktualizacją należy jednak wykonać kopię zapasową danych i sprawdzić informacje o zmianach niekompatybilnych z wcześniejszymi wersjami.

Usługi towarzyszące – MQTT, Zigbee2MQTT i proxy

Home Assistant w Dockerze często stanowi część większego środowiska kontenerowego. Typowy zestaw może obejmować następujące usługi:

• Home Assistant – główna platforma automatyki domowej;
• Mosquitto – broker MQTT obsługujący komunikację z czujnikami, sterownikami i innymi urządzeniami IoT;
• Zigbee2MQTT – usługa umożliwiająca obsługę urządzeń działających w sieci Zigbee;
• Nginx Proxy Manager – serwer proxy pozwalający skonfigurować domenę, certyfikat TLS i połączenia HTTPS;
• Duplicati lub inne narzędzie – rozwiązanie przeznaczone do wykonywania kopii zapasowych katalogów z danymi.

Dla usług korzystających ze standardowej sieci mostkowanej można utworzyć dedykowaną sieć Dockera, na przykład haoss_network. Kontenery podłączone do tej samej sieci mogą komunikować się za pomocą nazw usług.

Jeśli Home Assistant działa w trybie network_mode: host, połączenia z pozostałymi usługami należy skonfigurować z uwzględnieniem adresu hosta i udostępnionych portów.

Home Assistant w Dockerze na różnych platformach

Rozwiązanie kontenerowe można uruchomić na wielu platformach sprzętowych:

• Raspberry Pi i inne komputery jednopłytkowe – wymagają obrazu zgodnego z architekturą urządzenia oraz mapowania katalogu /config i, w razie potrzeby, ścieżki /run/dbus;
• Serwery x86-64 – mogą korzystać z tej samej konfiguracji docker run lub Docker Compose po dostosowaniu ścieżek i strefy czasowej;
• Intel NUC – może wykorzystywać tryb --network host oraz wolumen, na przykład /srv/homeautomation/hass-config:/config;
• Synology NAS – aplikacja Container Manager umożliwia pobranie oficjalnego obrazu oraz skonfigurowanie wolumenu, strefy czasowej, polityki restartu i sieci hosta.

Dzięki konteneryzacji Home Assistant może działać obok innych usług serwerowych, a jego konfigurację można stosunkowo łatwo przenosić między urządzeniami.

Najważniejsze dobre praktyki

Stabilność i bezpieczeństwo instalacji zależą przede wszystkim od poprawnego przechowywania danych, regularnych aktualizacji oraz ograniczenia dostępu do hosta. Warto przestrzegać następujących zasad:

1. używaj oficjalnego obrazu ghcr.io/home-assistant/home-assistant:stable albo konkretnej, wspieranej wersji;
2. przypisz hostowi stały adres IP, aby uniknąć problemów z dostępem do interfejsu i integracjami sieciowymi;
3. przechowuj dane Home Assistanta w dedykowanym katalogu na hoście, mapowanym jako /config;
4. stosuj ustawienie restart: unless-stopped, aby kontener automatycznie uruchamiał się po restarcie hosta;
5. ustaw prawidłową strefę czasową, na przykład TZ=Europe/Warsaw, ponieważ wpływa ona na harmonogramy automatyzacji;
6. korzystaj z Docker Compose oraz narzędzi takich jak Portainer lub Dockge, zwłaszcza gdy środowisko składa się z wielu usług;
7. regularnie aktualizuj obraz Home Assistanta i wykonuj kopie zapasowe całego katalogu /config;
8. sprawdzaj logi kontenera i monitoruj dostępność interfejsu na porcie 8123;
9. ograniczaj uprawnienia kontenera do niezbędnego minimum i używaj trybu privileged tylko wtedy, gdy wymaga tego konfiguracja sprzętowa;
10. zabezpiecz zdalny dostęp za pomocą HTTPS, silnego hasła i uwierzytelniania wieloskładnikowego.