Home assistant docker – jak zainstalować i poprawnie skonfigurować system?

Home Assistant to potężna platforma automatyzacji domowej, która pozwala na centralne zarządzanie wszystkimi urządzeniami smart home. Jedną z najpopularniejszych i najbardziej elastycznych metod instalacji jest uruchomienie w kontenerze Docker – od przygotowania środowiska, przez instalację, aż po pierwsze kroki konfiguracji.

Docker oferuje wiele zalet: łatwość wdrażania, niezależność od systemu operacyjnego, prostą aktualizację oraz możliwość uruchamiania wielu usług obok siebie. Jeśli jednak szukasz rozwiązania „out of the box” bez konieczności głębokiej wiedzy technicznej, Home Assistant OS będzie lepszym wyborem.

Czy Docker to dla Ciebie?

Kiedy wybrać instalację przez Dockera?

Wybierz Dockera, jeśli:

• posiadasz już doświadczenie z Dockerem w innych projektach,
• chcesz pełną kontrolę nad konfiguracją systemu,
• potrzebujesz elastyczności w zarządzaniu zasobami,
• planujesz uruchamiać Home Assistant obok innych kontenerów,
• preferujesz pracę z linią poleceń i plikami konfiguracyjnymi.

Alternatywy dla Dockera – jeśli rozważasz inne metody instalacji, oto najpopularniejsze opcje:

• Home Assistant OS – najprostsze rozwiązanie dla początkujących, instalowane na dedykowanym urządzeniu;
• Home Assistant Container – wersja Dockera, ale bez dostępu do Supervisor i oficjalnych dodatków;
• Home Assistant Core – minimalistyczne rozwiązanie dla zaawansowanych użytkowników pracujących z Pythonem.

Ograniczenia instalacji Dockera

Warto znać różnice względem Home Assistant OS:

• brak dostępu do Supervisor i oficjalnych dodatków (add‑ons),
• brak obsługi niektórych integracji wymagających dodatków lub usług systemowych (np. Thread, Z‑Wave),
• konieczność ręcznego zarządzania aktualizacjami.

Na urządzeniach takich jak Synology nie da się uzyskać pełnej funkcjonalności – w takim przypadku lepiej zainstalować Home Assistant OS na wirtualnej maszynie.

Wymagania wstępne

Sprzęt

Przygotuj następujące zasoby sprzętowe:

• komputer/serwer z systemem operacyjnym Linux, macOS lub Windows,
• dostęp do sieci (najlepiej przewód Ethernet dla stabilności),
• minimalnie 2 GB RAM (zalecane 4 GB lub więcej),
• 10 GB wolnego miejsca na dysku (dla podstawowej konfiguracji).

Wiedza techniczna

Wymagane podstawy:

• podstawowa znajomość terminala/wiersza poleceń,
• zrozumienie, czym jest Docker i kontenery,
• umiejętność edytowania plików tekstowych.

Oprogramowanie

Zainstaluj i przygotuj:

• Docker,
• Docker Compose,
• dowolny edytor tekstu (nano, vim lub graficzny edytor).

Krok 1 – instalacja Dockera

Ubuntu/Debian – oficjalna metoda

Poniżej znajdziesz oficjalną metodę instalacji Docker Engine i Docker Compose na systemach opartych na Ubuntu/Debianie:

1. Przygotowanie systemu

Najpierw usuń ewentualne stare wersje Dockera:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
sudo apt-get remove -y "$pkg"
done


2. Dodanie repozytorium Dockera

Zaktualizuj listę pakietów i zainstaluj wymagane narzędzia:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings


Pobierz i dodaj klucz GPG Dockera:

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc


Dodaj repozytorium Dockera do źródeł APT:

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(
. /etc/os-release && echo "$VERSION_CODENAME"
) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null


3. Instalacja Dockera

Uruchom instalację pakietów:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin


4. Weryfikacja instalacji

Sprawdź, czy Docker działa poprawnie:

docker --version
docker compose version


5. Restart systemu

Aby domknąć instalację, wykonaj restart:

sudo reboot


Instalacja na innych systemach

Fedora/CentOS – zainstaluj i uruchom usługę Dockera poleceniami:

sudo dnf install -y docker
sudo systemctl enable --now docker


macOS – pobierz i zainstaluj Docker Desktop: https://www.docker.com/products/docker-desktop

Windows – pobierz Docker Desktop dla Windows, włącz WSL 2 i dokończ instalację: https://www.docker.com/products/docker-desktop

Pełne instrukcje dla każdego systemu znajdziesz w dokumentacji Dockera: https://docs.docker.com/get-docker/

Krok 2 – przygotowanie struktury katalogów

Dobrze zorganizowana struktura katalogów ułatwi zarządzanie konfiguracją i tworzenie kopii zapasowych. Wykonaj:

Tworzenie katalogów

Utwórz katalog projektu i przejdź do niego:

mkdir -p ~/Docker/Home-Assistant
cd ~/Docker/Home-Assistant


Sprawdzenie struktury

Zweryfikuj bieżącą lokalizację i zawartość:

pwd
ls -la


Ścieżka powinna wyglądać mniej więcej tak:

/home/twoja_nazwa_uzytkownika/Docker/Home-Assistant


Krok 3 – tworzenie pliku Docker Compose

Plik docker-compose.yaml (lub compose.yaml) zawiera konfigurację kontenera Home Assistant. Poniżej gotowy przykład.

Utwórz plik konfiguracji

W katalogu ~/Docker/Home-Assistant utwórz plik o nazwie compose.yaml poleceniem:

nano compose.yaml


Wklej konfigurację

Skopiuj i wklej poniższą zawartość do pliku:

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


Wyjaśnienie konfiguracji

Najważniejsze opcje w pliku compose.yaml:

Opcja	Znaczenie
container_name: homeassistant	Nazwa kontenera – będzie widoczna w docker ps.
image: ghcr.io/home-assistant/home-assistant:stable	Pobiera najnowszą stabilną wersję Home Assistant.
./opt/homeassistant/config:/config	Mapuje folder na dysku do /config w kontenerze – tutaj przechowywane są konfiguracje.
/etc/localtime:/etc/localtime:ro	Synchronizuje strefę czasową systemu hosta z kontenerem (tylko do odczytu).
restart: unless-stopped	Automatycznie restartuje kontener przy starcie systemu.
privileged: true	Daje kontenerowi uprawnienia do dostępu do urządzeń (wymagane m.in. dla Z‑Wave, Thread).
network_mode: host	Pozwala kontenerowi na dostęp do sieci hosta – niezbędne dla wielu integracji.
TZ=Europe/Warsaw	Ustawia strefę czasową (dostosuj do swojej lokalizacji).

Zapisz plik

Aby zapisać w edytorze nano, użyj skrótów: Ctrl+S, a następnie Ctrl+X.

Aby zapisać w edytorze vim, naciśnij Esc, wpisz :wq i potwierdź klawiszem Enter.

Krok 4 – uruchamianie Home Assistant

Uruchomienie kontenera

Upewnij się, że jesteś w katalogu ~/Docker/Home-Assistant, a następnie uruchom:

docker compose up -d


Flaga -d uruchamia kontener w tle (detached mode).

Sprawdzenie statusu

Aby potwierdzić, że kontener działa:

docker compose ps


Powinna pojawić się informacja, że kontener homeassistant jest w stanie Up:

NAME COMMAND STATE PORTS
homeassistant "/init" Up 2 seconds


Przeglądanie logów

Aby zobaczyć logi instalacji i działania kontenera:

docker compose logs -f


Naciśnij Ctrl+C, aby zakończyć wyświetlanie logów.

Krok 5 – pierwsza konfiguracja

Dostęp do Home Assistant

Otwórz przeglądarkę i wpisz jeden z adresów:

http://localhost:8123


Lub, jeśli łączysz się z innego komputera w sieci, użyj adresu IP serwera:

http://192.168.1.X:8123


(zastąp X właściwą końcówką adresu IP)

Jak znaleźć adres IP serwera?

Adres IP sprawdzisz poleceniem:

hostname -I


Konfiguracja początkowa

Podczas pierwszego uruchomienia przejdź przez kreator:

1. Ekran powitalny – poczekaj, aż Home Assistant w pełni się załaduje (może to potrwać kilka minut przy pierwszym uruchomieniu);
2. Rejestracja konta – utwórz konto administratora;
3. Dane lokalizacji – podaj swoją lokalizację (do automatyzacji opartych o wschód/zachód słońca);
4. Wybór aplikacji – możesz pominąć na razie;
5. Dashboard – zobaczysz pusty pulpit, gotowy do personalizacji.

Ustawienie stałego adresu IP

Aby uniknąć problemów z dostępem, ustaw stały adres IP dla serwera.

Opcja 1: w routerze

• wejdź do panelu administracyjnego routera,
• znajdź sekcję DHCP,
• ustal rezerwację adresu IP dla swojego serwera (przypisz konkretny IP do jego adresu MAC).

Opcja 2: na serwerze (Linux)

Edytuj plik konfiguracyjny Netplan poleceniem:

sudo nano /etc/netplan/01-netcfg.yaml


Użyj konfiguracji podobnej do poniższej (dostosuj adresy do swojej sieci):

network:
version: 2
ethernets:
eth0:
dhcp4: no
addresses:
- 192.168.1.100/24
gateway4: 192.168.1.1
nameservers:
addresses: [8.8.8.8, 8.8.4.4]


Zastosuj zmiany:

sudo netplan apply


Krok 6 – zaawansowana konfiguracja

Rozszerzona konfiguracja Docker Compose

Jeśli potrzebujesz bardziej zaawansowanej konfiguracji, skorzystaj z rozszerzonego pliku compose.yaml:

version: "3.8"
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
restart: unless-stopped
privileged: true
network_mode: host
environment:
- TZ=Europe/Warsaw
devices:
- /dev/ttyUSB0:/dev/ttyUSB0
cap_add:
- NET_ADMIN
- NET_RAW
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8123"]
interval: 30s
timeout: 10s
retries: 3
start_period: 60s


Wyjaśnienie zaawansowanych opcji

Poniżej znajdziesz znaczenie najważniejszych dodatkowych wpisów:

Opcja	Znaczenie
/run/dbus:/run/dbus:ro	Pozwala na komunikację z usługami systemowymi (np. Bluetooth).
/dev/ttyUSB0:/dev/ttyUSB0	Mapuje urządzenie USB (np. dla sticka Z‑Wave/Zigbee).
cap_add	Dodaje uprawnienia Linuksa (np. NET_ADMIN, NET_RAW dla sieci).
healthcheck	Okresowo sprawdza, czy kontener działa prawidłowo.

Tworzenie kopii zapasowej

Kopia zapasowa jest kluczowa dla bezpieczeństwa Twojej konfiguracji. Wykonaj backup ręcznie poleceniami:

# Zrób kopię całego folderu config
cp -r ~/Docker/Home-Assistant/opt/homeassistant/config ~/Home-Assistant-backup-$(date +%Y%m%d)

# Alternatywnie – zrób archiwum
tar -czf ~/Home-Assistant-backup-$(date +%Y%m%d).tar.gz ~/Docker/Home-Assistant/opt/homeassistant/config

Ustawienie automatycznych kopii zapasowych

Dodaj zadanie CRON, aby wykonywać automatyczny backup:

crontab -e


Następnie dodaj linię (dostosuj ścieżki do swojego użytkownika):

0 2 * * * tar -czf /home/uzytkownik/backups/ha-backup-$(date +\%Y\%m\%d).tar.gz /home/uzytkownik/Docker/Home-Assistant/opt/homeassistant/config


To utworzy kopię zapasową codziennie o 2:00 w nocy.

Krok 7 – integracja zdalnego dostępu (Nabu Casa)

Aby dostać się do Home Assistant spoza domowej sieci, skorzystaj z jednej z opcji:

Opcja 1 – Nabu Casa (rekomendowane)

1. W Home Assistant przejdź do Ustawienia → Automatyzacja i sceny → Nabu Casa;
2. Zaloguj się kontem Home Assistant Cloud;
3. Aktywuj dostęp zdalny;
4. Home Assistant będzie dostępny pod adresem: https://[random-string].nabu.casa.

Opcja 2 – VPN (zaawansowane)

Użyj WireGuard lub OpenVPN do bezpiecznego dostępu z zewnątrz (wymaga konfiguracji serwera VPN).

Zarządzanie kontenerem

Podstawowe komendy

Poniżej najczęściej używane polecenia w katalogu projektu:

# Przejdź do katalogu
cd ~/Docker/Home-Assistant

# Sprawdzenie statusu
docker compose ps

# Przeglądanie logów
docker compose logs -f homeassistant

# Zatrzymanie kontenera
docker compose down

# Uruchomienie kontenera
docker compose up -d

# Restart kontenera
docker compose restart

# Usunięcie kontenera (dane w katalogu ./opt/homeassistant/config pozostaną)
docker compose down -v

Aktualizacja Home Assistant

W instalacji Docker należy ręcznie zarządzać aktualizacjami. Aby zaktualizować do najnowszej wersji, wykonaj:

cd ~/Docker/Home-Assistant
docker compose pull
docker compose up -d


Monitorowanie zasobów

Aby zobaczyć bieżące użycie CPU, RAM i IO kontenera:

docker stats homeassistant


Rozwiązywanie problemów

Problem – „connection refused” przy dostępie do localhost:8123

Przyczyna – kontener może się jeszcze ładować lub nie został uruchomiony.

Rozwiązanie – sprawdź status i logi:

docker compose ps
docker compose logs


Przy pierwszym uruchomieniu odczekaj kilka minut.

Problem – Home Assistant nie widzi urządzeń Z‑Wave/Zigbee

Przyczyna – brakuje mapowania urządzenia USB w pliku compose.yaml.

Rozwiązanie – wykonaj kroki:

1. Znajdź port USB: ls /dev/tty*;
2. Dodaj do compose.yaml poniższy fragment:

devices:
- /dev/ttyUSB0:/dev/ttyUSB0


3. Zrestartuj kontener: docker compose restart.

Problem – brak dostępu do internetu z kontenera

Przyczyna – sieć hosta nie jest dostępna.

Rozwiązanie – upewnij się, że używasz network_mode: host w compose.yaml.

Problem – brak dostępu do Bluetooth

Przyczyna – brak dostępu do D-Bus.

Rozwiązanie – dodaj poniższy wolumen w compose.yaml:

volumes:
- /run/dbus:/run/dbus:ro


Optymalizacja wydajności

Ograniczenie zasobów

W konfiguracji zaawansowanej możesz ograniczyć zużycie zasobów przez kontener:

deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
reservations:
cpus: "0.5"
memory: 256M


Czyszczenie dzienników

Home Assistant potrafi generować duże logi. Aby ograniczyć zużycie dysku, zmień poziom logowania w configuration.yaml:

logger:
default: warning
logs:
homeassistant.core: info


Optymalizacja bazy danych

Historia przechowywana jest w bazie SQLite. Dodaj do configuration.yaml ustawienia czyszczenia i wykluczeń:

recorder:
auto_purge: true
auto_purge_keep_days: 30
exclude:
domains:
- automation
- scene


Instalacja na Raspberry Pi 3

Jeśli używasz Raspberry Pi 3 z systemem Linux (Raspberry Pi OS), wykonaj:

1. Zainstaluj Dockera poleceniami:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker pi


2. Zainstaluj Docker Compose:

sudo apt-get install -y python3-pip
sudo pip3 install docker-compose


3. Postępuj zgodnie z krokami 2–5 opisanymi wyżej.

Uwaga: Raspberry Pi 3 ma ograniczone zasoby – dla większych instalacji rekomendowane jest minimum Raspberry Pi 4 lub nowsze.

Instalacja na Fedorze/CentOS z Podmanem

Jeśli wolisz Podman zamiast Dockera, użyj następujących poleceń:

sudo dnf install -y podman
mkdir -p ~/hass_config
podman run --init -d \
--name homeassistant \
--restart=unless-stopped \
-v /etc/localtime:/etc/localtime:ro \
-v ~/hass_config:/config:Z \
--network=host \
homeassistant/home-assistant:stable


Zasoby i linki pomocne

Poniżej znajdziesz przydatne źródła do pogłębiania wiedzy:

• Oficjalna dokumentacja Home Assistant – https://www.home-assistant.io;
• Dokumentacja Dockera – https://docs.docker.com;
• Forum społeczności Home Assistant – https://forum.home-assistant.io;
• Discord społeczności – https://discord.gg/home-assistant.

Autor – Poradnik Smart Home | Ostatnia aktualizacja – 2026