Home Assistant Container bir sunucuda Docker ile nasıl çalıştırılır

Home Assistant; binlerce entegrasyonu, görsel otomasyon düzenleyicisi ve özelleştirilebilir panoları olan açık kaynaklı bir ev otomasyonu platformudur. Home Assistant Container kurulumu, çekirdek uygulamayı resmi ghcr.io/home-assistant/home-assistant imajından Docker ile çalıştırır.

Onu evdeki bir cihaz yerine kiralık bir sunucuda çalıştırmak yapabileceklerini değiştirir: USB radyo yoktur ve cihaz keşfedilecek bir yerel ağ yoktur. Buna karşılık her zaman çevrim içi olan, her yerden erişilebilen ve evinizi bir VPN üzerinden yönetebilen bir hub elde edersiniz. Bu rehber Home Assistant Container'ı projenin belgelediği gibi Docker Compose ile kurar, ilk kurulumu bir SSH tüneli üzerinden yapar, onu Caddy ve gerekli güvenilen proxy ayarlarıyla HTTPS üzerinden yayınlar, WireGuard ile evinize bağlar ve yedekleme ile güncellemeyi anlatır.

Adım 1 — Compose dosyasını oluşturun

config alt klasörü olan bir proje klasörü, ardından Compose dosyasını oluşturun:

sudo mkdir -p /opt/homeassistant/config
sudo chown -R $USER:$USER /opt/homeassistant
cd /opt/homeassistant
nano compose.yaml

Config yolu doldurulmuş resmi örneği yapıştırın ve TZ değerini kendi saat diliminize ayarlayın:

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
    stop_grace_period: 60s
    privileged: true
    network_mode: host
    environment:
      TZ: Europe/Amsterdam

network_mode: host, Home Assistant'ın sunucunun ağını doğrudan kullanmasını sağlar; birçok entegrasyon bunu bekler. Bu aynı zamanda 8123 numaralı portun sıradan bir sunucu portu olduğu anlamına gelir; yani Docker'ın yayınladığı portların aksine ufw onu filtreler.

Adım 2 — Güvenlik duvarını kapatın ve Home Assistant'ı başlatın

8123 numaralı port internete kapalı kalsın diye yalnızca SSH'ye izin verin, ardından konteyneri başlatın:

sudo ufw allow OpenSSH
sudo ufw enable
docker compose up -d
docker compose ps
docker compose logs -f homeassistant

Log kurulum mesajlarını göstermeyi bırakana kadar bekleyin, ardından Ctrl+C'ye basın. Home Assistant'ın yerelde yanıt verdiğini kontrol edin:

curl -I http://127.0.0.1:8123
sudo ss -tlnp | grep 8123

curl HTTP başlıklarını yazdırır; ss ise Home Assistant'ın tüm adreslerde dinlediğini gösterir ve ufw bunu artık dışarıdan engeller.

Adım 3 — İlk kurulumu SSH tüneli üzerinden yapın

Home Assistant'ı ilk açan kişi sahip (owner) hesabını oluşturur. Bunu bir tünel üzerinden yapın. Kendi bilgisayarınızda şunu çalıştırın:

ssh -L 8123:127.0.0.1:8123 admin@203.0.113.10

http://localhost:8123 adresini açın, Create my smart home seçeneğini seçin ve bir ad, küçük harfli bir kullanıcı adı ve güçlü bir parola girin. Home Assistant sahip hesabı bilgilerinin kurtarılamayacağı konusunda uyarır; bu yüzden onları bir parola yöneticisinde saklayın. Ardından saat dilimini, birim sistemini ve para birimini de belirleyen ev konumunuzu ayarlayın, hangi anonim verileri paylaşacağınızı seçin (paylaşım varsayılan olarak kapalıdır) ve Finish seçeneğini seçin.

Çok aşamalı doğrulamayı hemen açın: kullanıcı profilinizi açın, Security sekmesine gidin ve kimlik doğrulayıcı uygulama (authenticator app) modülünü etkinleştirin.

Adım 4 — Caddy'yi reverse proxy olarak güvenilir yapın

Home Assistant, siz izin vermedikçe reverse proxy'lerden gelen istekleri engeller. Host ağında aynı sunucudaki Caddy 127.0.0.1 (veya ::1) adresinden bağlanır. 2026.8 sürümünden beri bu ayarlar configuration.yaml içinde değil, arayüzde bulunur:

1. Settings → System → Network sayfasına gidin ve HTTP server bölümünü bulun.
2. Trust X-Forwarded-For seçeneğini açın.
3. Trusted proxies listesine 127.0.0.1 ve ::1 ekleyin.
4. Enable IP banning seçeneğini açın ve Login attempts before ban değerini 5 gibi düşük bir sayıya ayarlayın.
5. Kaydedin. Home Assistant yeniden başlar ve ardından yeni ayarları onaylamanız gerekir; aksi hâlde 5 dakika sonra önceki ayarlara döner.

configuration.yaml içinde hâlâ bir http: bloğu bulunan eski bir kurulumu yükseltirseniz Home Assistant bu bloğu bir kez bu ayarlara aktarır ve ardından bloğu kaldırmanızı isteyen bir onarım (repair) gösterir.

Adım 5 — Home Assistant'ı Caddy ile HTTPS üzerinden yayınlayın

Web portlarını açın ve /etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. Caddy, Home Assistant arayüzünün kullandığı WebSocket bağlantılarını ek ayar gerekmeden aktarır:

ha.example.com {
    reverse_proxy 127.0.0.1:8123
}

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo systemctl reload caddy
curl -I https://ha.example.com

Geçerli bir sertifikayla HTTP yanıtı almalısınız. Bağlantıların ve yardımcı (companion) uygulamaların bu adresi kullanması için Settings → System → Network altında internet için Home Assistant adresini https://ha.example.com olarak ayarlayın.

Adım 6 — Evdeki cihazlarınıza WireGuard üzerinden ulaşın

Sunucudaki Home Assistant yalnızca ağ üzerinden ulaşabildiği cihazları yönetebilir. Olağan düzen siteden siteye (site-to-site) bir VPN'dir: sunucu WireGuard çalıştırır, evdeki bir yönlendirici veya küçük bir cihaz ise ev alt ağınızı (örneğin 192.168.1.0/24) yönlendiren bir eş (peer) olarak katılır. Bunu WireGuard VPN sunucusu nasıl kurulur rehberiyle kurun ve ev alt ağını o eşin izin verilen IP'lerine (allowed IPs) ekleyin.

Sunucudan evdeki bir cihazın yanıt verdiğini kontrol edin, ardından entegrasyonunu Home Assistant'ta IP adresiyle ekleyin:

ping -c 3 192.168.1.10

Otomatik keşif (mDNS, SSDP) yönlendirilen bir VPN'i aşamaz; bu yüzden cihazlar kendiliğinden bulunmaz, ancak çoğu entegrasyon adresi elle girmenize izin verir. VPN'i, Home Assistant'ı Caddy ile yayınlamak yerine telefonunuzdan açmak için de kullanabilirsiniz. Porta yalnızca VPN arayüzünde izin verin:

sudo ufw allow in on wg0 to any port 8123 proto tcp

Yedekleme ve geri yükleme

Home Assistant'ın bildiği her şey config klasöründe, /opt/homeassistant/config içinde durur: configuration.yaml, panoları ve entegrasyonları tutan gizli .storage klasörü ve geçmiş veritabanı.

Arayüzden yedekler. Settings → System → Backups sayfasına gidin, Backup now ve ardından Manual backup seçeneğini seçin ya da eski yedekleri de silen otomatik yedeklemeyi kurun. Acil durum kitini (emergency kit) indirin ve güvenli bir yerde saklayın; şifreli yedekleri geri yüklemek için gereken anahtarı içerir. Container'da yerel yedekler, koruduğu klasörün içine, /opt/homeassistant/config/backups konumuna yazılır; bu yüzden onları başka bir yere kopyalayın veya aynı ekrandan bir ağ ya da bulut yedek konumu ekleyin.

Klasör yedeği. Konteyneri durdurun, config klasörünün tamamını arşivleyin ve konteyneri yeniden başlatın:

sudo mkdir -p /opt/backups
cd /opt/homeassistant
docker compose stop
sudo tar czf /opt/backups/homeassistant-config-$(date +%F).tar.gz -C /opt/homeassistant config
docker compose start

/opt/backups klasörünü rsync veya scp ile başka bir makineye kopyalayın.

Geri yükleme. Arayüzde Settings → System → Backups sayfasını açın, bir yedek seçin ve Restore seçeneğini seçin. Yeni bir kurulumda karşılama ekranı, yeni bir ev oluşturmak yerine bir yedek yüklemenize izin verir. Klasör arşivini geri yüklemek için konteyneri durdurun, mevcut klasörü kenara taşıyın ve arşivi açın:

cd /opt/homeassistant
docker compose down
sudo mv config config.old
sudo tar xzf /opt/backups/homeassistant-config-2026-10-09.tar.gz -C /opt/homeassistant
docker compose up -d

Home Assistant güncelleme

Önce sürüm notlarını, özellikle Backward-incompatible changes bölümünü okuyun ve bir yedek alın. Ardından Container belgelerinde anlatıldığı gibi yeni imajı çekin ve konteyneri yeniden oluşturun:

cd /opt/homeassistant
docker compose pull homeassistant
docker compose up -d
docker image prune

Sonrasında Settings → System → Repairs sayfasını ve logları kontrol edin. stable etiketi her zaman en son kararlı sürümü gösterir. Güncellemeleri denetlemek için onu 2026.10.0 gibi belirli bir sürüm etiketiyle değiştirin; bu aynı zamanda önceki bir sürüme dönmenizi de sağlar.

Elle yaptığınız YAML değişikliklerinden sonra yeniden başlatmadan önce yapılandırmayı doğrulayın:

docker exec homeassistant python -m homeassistant --script check_config --config /config

Sorun giderme

Alan adını açtığınızda 400: Bad Request

Home Assistant proxy'ye güvenmiyor. Adım 4'ü tekrarlayın, güvenilen proxy'ler arasında hem 127.0.0.1 hem de ::1 bulunduğundan emin olun, ardından docker compose logs homeassistant ile logda reverse proxy'den gelen bir istekle ilgili mesaj olup olmadığına bakın.

Ağ ayarları birkaç dakika sonra geri döndü

HTTP server ayarlarını kaydettikten sonra Home Assistant yeniden başlar ve bir yöneticinin onları onaylamasını bekler. 5 dakika içinde kimse onaylamazsa önceki ayarları geri yükler. Yeniden kaydedin ve onaylayın.

Tarayıcınızdan 8123 numaralı porta ulaşılamıyor

Bu amaçlanan davranıştır: ufw portu engeller. SSH tünelini, VPN'i veya Caddy alan adını kullanın. WireGuard üzerinden erişim bekliyorsanız wg0 kuralının var olduğunu sudo ufw status ile kontrol edin.

Evdeki cihazlar keşfedilmiyor

Keşif protokolleri VPN'i aşamaz. Sunucunun cihaza ping ile ulaşabildiğini kontrol edin, ardından entegrasyonu cihazın IP adresiyle elle ekleyin. ping başarısız olursa ev alt ağı WireGuard eşinin izin verilen IP'lerinde eksiktir veya ev yönlendiricisi onu yönlendirmiyordur.

configuration.yaml düzenlendikten sonra Home Assistant başlamıyor

Bir YAML hatası yapılandırmanın yüklenmesini durdurur. Güncelleme bölümündeki check_config komutunu çalıştırın, bildirilen satırları düzeltin ve konteyneri docker compose up -d ile yeniden başlatın.

Sonraki adımlar

• Sunucuyu ev ağınıza WireGuard VPN sunucusu ile bağlayın.
• HTTPS ve site blokları hakkında daha fazlasını Caddy reverse proxy olarak nasıl kurulur rehberinde öğrenin.
• Docker Compose temelleri ile daha fazla servisi konteyner olarak ekleyin.
• Ev otomasyonu için sunucuları Home Assistant hosting sayfasında karşılaştırın.
• Entegrasyonları Home Assistant belgelerinde keşfedin.