Home Assistant w Docker Compose: konfiguracja, sieci i aktualizacje krok po kroku

Dlaczego warto uruchomić Home Assistant w Docker Compose

Instalacja Home Assistant jako kontenera w Docker Compose daje coś, czego nie znajdziesz w gotowych obrazach systemu: pełną kontrolę nad tym, co dzieje się w środku. Sam decydujesz o wersji, sieci, wolumenach i sposobie aktualizacji. To nie czarna magia.

W podejściu opartym na Dockerze aktualizacja to podmiana tagu obrazu i ponowne uruchomienie stosu. Jeśli coś pójdzie nie tak, wracasz do poprzedniej wersji w kilka minut. Przy instalacji natywnej rollback bywa bardziej zawiły, a przy Home Assistant OS w ogóle nie masz takiej swobody, bo system zarządza sobą sam.

Do tego dochodzi separacja. Kontener żyje obok innych usług, na przykład bazy danych czy brokera MQTT, i każde z nich możesz aktualizować niezależnie. Diabeł tkwi w szczegółach, więc zobacz, co realnie zyskujesz:

• Izolacja środowiska, bo zależności Home Assistant nie mieszają się z resztą systemu.
• Powtarzalna konfiguracja, ponieważ cały stos opisujesz w jednym pliku YAML.
• Prosty rollback do wcześniejszego obrazu, gdy nowa wersja sprawia problemy.
• Wolny wybór dodatków, bo nie jesteś ograniczony do sklepu z dodatkami.
• Łatwa migracja na inny serwer, wystarczy przenieść katalogi i plik Compose.
• Kontrola nad siecią, od trybu host po własne mostki Docker.

Moim zdaniem Docker Compose działa lepiej niż Home Assistant Supervised, ponieważ Supervised wymaga konkretnej dystrybucji Linuksa i potrafi się zepsuć przy aktualizacji systemu, a Compose jest niezależny od tego, co siedzi pod spodem. Cena? Musisz sam pilnować backupów i aktualizacji.

A co jeśli nie chcesz się tym przejmować? Wtedy OS albo Supervised bywają wygodniejsze. O różnicach między tymi trzema podejściami piszę szerzej w osobnym artykule o wyborze metody instalacji.

Przygotowanie środowiska i plik docker-compose.yaml

Zanim wkleisz pierwszą linijkę konfiguracji, upewnij się, że masz na czym pracować. Potrzebujesz systemu z zainstalowanym Docker Engine i pluginem Compose. Na większości popularnych dystrybucji Linuksa wystarczy kilka poleceń z oficjalnej dokumentacji. Windows i macOS? Docker Desktop załatwia sprawę, choć przy Home Assistant lepiej postawić na osobny mini PC albo serwer.

Osobny katalog to podstawa. Trzymanie plików konfiguracyjnych w losowym miejscu to proszenie się o kłopoty przy aktualizacjach. Stwórz folder, na przykład /opt/homeassistant, i tam umieść plik docker-compose.yaml oraz katalog config na dane.

Co powinno znaleźć się w samym pliku? Poniższa tabela pokazuje najważniejsze elementy, które warto uwzględnić od początku:

Zwróć uwagę na network_mode: host. W trybie host kontener widzi urządzenia w sieci lokalnej bez dodatkowej konfiguracji. To upraszcza integrację z Zigbee, Matter czy urządzeniami sieciowymi. Minus? Kontener nie jest odizolowany od sieci hosta. Wybór należy do ciebie, ale dla większości domowych instalacji host bywa wygodniejszy.

Nie zapomnij o katalogu config. Docker sam go nie stworzy, a bez niego kontener wstanie z pustą konfiguracją. Jeden folder, a potrafi zaoszczędzić sporo nerwów. I tu zaczyna się problem, jeśli pominiesz ten krok.

Konfiguracja sieci: host, bridge i dostęp zdalny

Wybór trybu sieci w Docker Compose to jedna z tych decyzji, które później trudno cofnąć bez rozbierania całego stacku. Domyślny bridge izoluje kontener, ale wtedy Home Assistant nie widzi urządzeń w sieci lokalnej. To poważny problem, jeśli korzystasz z integracji po IP, np. z telewizorem, drukarką czy kamerą.

Tryb network_mode: host rozwiązuje większość takich przypadków. Kontener dostaje bezpośredni dostęp do interfejsów hosta, więc autodiscovery działa od razu, a mDNS nie sprawia kłopotów. Cena? Tracisz izolację i nie możesz mapować portów przez sekcję ports, bo Docker zgłosi konflikt.

Zdalny dostęp to osobny temat. Moim zdaniem Tailscale działa lepiej niż klasyczne przekierowanie portów na routerze, ponieważ nie wystawiasz instancji Home Assistant bezpośrednio do internetu, a szyfrowanie masz po stronie VPN. Otwieranie portu 8123 na świat to proszenie się o kłopoty, choćby ze względu na boty skanujące.

Typowy przykład: masz HA w kontenerze, chcesz wejść z telefonu poza domem i nie chcesz stawiać osobnego serwera VPN. Tailscale albo Cloudflare Tunnel załatwiają sprawę w kilku krokach. A co jeśli nie chcesz żadnej chmury? Zostaje WireGuard na routerze. Więcej o wyborze wariantu instalacji znajdziesz w tekście o Home Assistant OS vs Supervised vs Container.

Trwałość danych, wolumeny i kopie zapasowe

Kontener bez wolumenu to dom bez fundamentów. Restart Dockera, aktualizacja obrazu albo zwykły crash i cała konfiguracja znika. Home Assistant trzyma w /config wszystko, co ważne: plik configuration.yaml, bazę historii, integracje, tokeny, dodatki. Jeśli ten katalog siedzi tylko wewnątrz kontenera, dane przepadają przy pierwszym większym błędzie. Brzmi dramatycznie? Bo tak jest.

Rozwiązanie jest proste: mapujesz katalog z hosta na ścieżkę w kontenerze. W pliku docker-compose.yaml wystarczy wpis w sekcji volumes, na przykład ./config:/config. Wtedy pliki leżą na dysku serwera, a kontener tylko z nich korzysta. Możesz podmienić obraz, zmienić wersję, przenieść instalację na inny sprzęt i nic nie tracisz.

Sam wolumen to jeszcze nie backup. Kopia na tym samym dysku chroni przed błędem konfiguracji, ale nie przed awarią nośnika. Diabeł tkwi w szczegółach.

Wyobraź sobie sytuację, w której po nieudanej aktualizacji kontener nie wstaje, a ty masz tylko snapshot sprzed miesiąca. Bez świeżej kopii odtwarzasz integracje ręcznie, wieczór po wieczorze. Automatyzacja kopii to nie fanaberia, to ubezpieczenie.

Moim zdaniem snapshot wbudowany w Home Assistant działa lepiej niż ręczne kopiowanie katalogu przez rsync, ponieważ tworzy spójny pakiet konfiguracji i dodatków, a rsync potrafi złapać bazę w trakcie zapisu. I jedno, i drugie warto jednak wypychać poza serwer.

Aktualizacje, wersjonowanie i aktualizacja obrazu bez przestojów

Docker Compose daje jedną rzecz, której brakuje wielu metodom instalacji: kontrolę nad tym, kiedy i jak aktualizujesz Home Assistant. Obraz kontenera aktualizujesz wtedy, gdy sam zdecydujesz. Nie ma przymusowego restartu w środku dnia, nie ma niespodzianek.

Mechanizm jest prosty. Podmieniasz tag obrazu na nowszy, pobierasz go i odtwarzasz kontener. Tylko że diabeł tkwi w szczegółach. Jeśli zrobisz to bez przygotowania, stracisz kilka minut na diagnostykę, bo nowa wersja może wymagać migracji bazy danych.

Dlatego przed każdą aktualizacją rób kopię zapasową katalogu konfiguracyjnego. To nie czarna magia, wystarczy zwykłe archiwum. Wersjonowanie obrazów w Dockerze działa na tagach, a te bywają mylące, jeśli nie wiesz, czego szukasz.

Moim zdaniem przypinanie konkretnej wersji działa lepiej niż tag stable, ponieważ wiesz dokładnie, co masz uruchomione, a aktualizację planujesz świadomie. Tag stable jest wygodny, ale zmienia się bez ostrzeżenia przy każdym restarcie kontenera z pobieraniem obrazu.

Zero przestoju? W praktyce trudne przy samym Home Assistant, bo restart usługi trwa kilkanaście sekund. Ale możesz to zaplanować na noc albo użyć mechanizmu healthcheck, żeby nowy kontener wstał dopiero po poprawnej inicjalizacji. Wtedy przerwa jest krótka i przewidywalna. A co jeśli aktualizacja się nie powiedzie? Wracasz do poprzedniego obrazu, bo stary kontener wciąż masz. To właśnie przewaga kontenera nad instalacją natywną.

Najczęściej zadawane pytania (FAQ)

Pytania o Home Assistant w Docker Compose wracają jak bumerang. Nic dziwnego, bo jeden błąd w konfiguracji potrafi zablokować cały system na kilka godzin. Poniżej zebrałem odpowiedzi na to, o co pytacie najczęściej.

Czy Docker Compose to dobry wybór na start? Zależy, czego oczekujesz. Jeśli lubisz mieć kontrolę nad każdym elementem i nie przeszkadza ci ręczna aktualizacja, to dobry kierunek. Jeśli szukasz rozwiązania "włącz i zapomnij", lepszy będzie Home Assistant OS. Porównanie wszystkich trzech wariantów znajdziesz w naszym artykule o Home Assistant OS vs Supervised vs Container szerzej opisaliśmy to w artykule "Home assistant os vs supervised vs container".

Moim zdaniem network_mode: host działa lepiej niż bridge w typowym domowym wdrożeniu, ponieważ wiele integracji opiera się na wykrywaniu urządzeń w sieci lokalnej, a mostkowanie sieci w Dockerze potrafi to skutecznie utrudnić. Diabeł tkwi w szczegółach, ale akurat ten szczegół warto ustawić raz i mieć spokój.

Typowy przykład: ktoś przenosi konfigurację z Home Assistant OS na kontener, zapomina o wolumenie i po pierwszej aktualizacji traci całą automatyzację. Brzmi banalnie? Zdarza się częściej, niż myślisz. Dlatego zawsze sprawdź, czy ścieżka /config jest podpięta do trwałego wolumenu, zanim uruchomisz stack produkcyjnie.

Masz pytanie, którego tu nie ma? Napisz w komentarzu, chętnie rozwinę temat w kolejnym wpisie.