스마트홈 기기가 늘어나면 어느 순간 벽에 부딪힌다. 제조사마다 앱이 다르고, 자동화는 앱마다 반쪽짜리고, 기기가 클라우드에만 의존하면 인터넷이 끊겼을 때 전등 하나 못 켠다. Home Assistant(이하 HA)는 이 문제에 대한 오픈소스 답이다. 집안의 기기를 한곳에 모아, 하나의 대시보드에서 보고, 하나의 자동화 엔진으로 묶어준다. 이 글은 HA를 우분투 서버의 도커 컨테이너로 설치하고 스마트라이프(튀야) 기기와 전력 계량까지 연동한 과정을 순서대로 담았다.
스마트홈 도구를 찾게 되는 순간은 사람마다 다르지만, 대체로 이런 상황들이다.
HA는 이 모든 것을 하나의 화면과 하나의 자동화 규칙으로 묶어주는 도구다. 코딩 지식은 필요 없다. 필요한 것은 서버 한 대뿐이다.
한 문장으로 정리하면 기기 제조사와 상관없이 집안의 모든 스마트 기기를 하나로 묶는 오픈소스 허브다. 2005년부터 시작된 프로젝트로, 현재 2,500개가 넘는 공식 통합(기기·서비스 연결 모듈)을 갖고 있다. 튀야, 샤오미, 삼성 스마트싱스, 애플 홈킷 호환 기기, IPTime 공유기까지 — 웬만한 기기는 이미 통합이 존재한다.
HA가 하는 일은 크게 여섯 가지로 요약된다.
| 기능 | 하는 일 | 예시 |
|---|---|---|
| 통합(Integration) | 서로 다른 제조사 기기를 하나의 체계로 | 스마트플러그·커튼·도어락·카메라를 한 화면에 |
| 자동화(Automation) | 트리거-조건-동작으로 기기 묶기 | 일몰 30분 전 조명 켜기, 외출 감지 시 에어컨 끄기 |
| 대시보드(Dashboard) | 모바일/웹용 조작 화면 | 집 전체 상태를 한 화면에서 스위치·슬라이더로 |
| 에너지(Energy) | 전력 소비 계량·시각화 | 콘센트별 월간 전기요금 그래프 |
| 알림(Notification) | 폰으로 이벤트 전달 | 문 열림·사람 감지·세탁 완료 푸시 |
| 로그북(Logbook) | 집안에서 일어난 일의 이력 | "어제 밤 11시에 현관 문이 열렸다" |
상용 스마트홈 앱과의 결정적 차이는 데이터와 로직이 내 손에 있다는 것이다. 자동화가 클라우드가 아니라 내 서버에서 돌고, 기기 상태 이력이 내 데이터베이스에 쌓이고, 제조사가 서비스를 종료해도 내 시스템은 멈추지 않는다. 그 대가로 설치와 유지보수는 내 몫이다 — 이 글은 그 몫을 다루는 글이다.
HA의 설치 형태는 셋이다. HAOS(전용 OS를 통째로 설치), Supervised(데비안 위에 설치), 그리고 컨테이너(도커).
| 방식 | 애드온 스토어 | 적합한 사람 |
|---|---|---|
| HAOS (라즈베리파이 등) | 있음 | HA만 할 수 있는 전용 기기를 둘 사람 |
| Supervised | 있음 | 데비안에서 전체 기능을 원하는 사람 |
| 컨테이너 | 없음 | 이미 서버를 운영 중인 사람 |
필자는 이미 우분투 서버 한 대로 CCTV 녹화, 파일 서버, 웹 서비스를 도커로 돌리고 있었기 때문에 컨테이너를 골랐다. 애드온이 없다는 게 가장 큰 걸림돌처럼 보이지만, 애드온의 실체는 미리 패키징된 컨테이너일 뿐이라 같은 docker-compose에 직접 추가하면 된다. Mosquitto(MQTT 브로커)도 Frigate(NVR)도 그렇게 붙였다.
컨테이너 설치의 또 다른 장점은 설정이 하나의 디렉터리에 고정된다는 점이다. 백업은 그 디렉터리를 통째로 복사하는 것으로 끝나고, 서버를 옮길 때도 디렉터리만 들고 가면 된다.
# docker-compose.yml
services:
homeassistant:
container_name: homeassistant
image: ghcr.io/home-assistant/home-assistant:stable
volumes:
- /opt/docker/homeassistant/data:/config # 설정이 전부 여기 고정된다
network_mode: host # 기기 자동 검색용
restart: unless-stopped
docker compose up -d
network_mode: host는 mDNS/SSDP 기반 기기 자동 검색과 USB 블루투스 동글 사용을 위해 붙인다. 브리지 네트워크로도 운영은 가능하지만 검색 기능을 포기하게 된다.
브라우저로 http://서버IP:8123을 열면 온보딩이 시작된다. 관리자 계정을 만들고, 집 위치(일출·일몰 자동화에 쓰인다)를 등록하면 기본 준비가 끝난다.
이 시점에서 반드시 확인할 것이 하나 있다. /config/configuration.yaml의 첫 줄에 이것이 있는지 보자.
default_config:
이 한 줄이 주석처리된 채 배포되는 경우가 은근히 있는데, 이 줄이 없으면 recorder, energy, history, logbook — HA라고 부를 수 있는 기능의 절반 — 이 아예 로드되지 않는다. 필자는 첫날 에너지 메뉴가 안 보여서 여기서 한참을 헤맸다.
집 밖에서 접속하려면 도메인을 붙이고 리버스 프록시(Caddy/Nginx) 뒤에 두는 게 정석이다. 이때 빠뜨리면 로그인 페이지가 무한 새로고침되는 설정이 있다.
http:
use_x_forwarded_for: true
trusted_proxies:
- 172.18.0.0/16 # 프록시 컨테이너가 속한 도커 네트워크 대역
모바일 companion 앱의 푸시 알림도 이 외부 경로를 통해 이뤄지므로, 집밖 알림이 필요하면 이 단계는 필수다.
국내에서 파는 저가 스마트플러그·커튼·도어락 상당수가 스마트라이프 앱으로 동작한다. HA에는 공식 Tuya 통합이 있어서 이 기기들을 그대로 가져올 수 있다.
설정 → 기기 및 서비스 → 통합 추가 → "Tuya" 검색 → QR 로그인 방식을 고른다(2024년 8월부터 API 키 발급 방식이 폐기되고 QR 로그인으로 바뀌었다 — 오래된 블로그 글은 옛 방식만 소개하니 주의). 이 과정에서 경험한 헤매는 지점 세 곳을 그대로 공유한다.
첫째, QR 스캐너가 두 개다. 화면의 QR은 스마트라이프 앱 첫 화면의 + 버튼 스캐너로 찍으면 안 되고, 우측 하단 나(Me) 탭 → 우측 상단 스캔 아이콘으로 찍어야 한다. 기기 추가용과 계정 로그인용이 따로 존재한다.
둘째, 인증 경로가 섞여 있다. QR 로그인 연동은 일부 단계가 REST로, 일부는 WebSocket으로 진행된다. 화면에서 따라가는 데는 문제없지만 스크립트로 자동화할 때는 이 차이를 알아야 한다.
셋째, 연동했는데 기기가 안 보인다면 기기가 비활성화 상태일 확률이 높다. 필자는 재연동을 몇 번 하고도 기기 목록이 비어 있어서 원인을 못 찾았는데, 설정 → 기기 → 해당 기기 → 활성화를 켜자 엔티티가 나타났다. 제조사가 출고 때 꺼둔 센서(전력 계량 등)도 같은 방식으로 기기 페이지 안에서 수동 켜줘야 한다.
연동을 하다 보면 알게 되는 사실이 하나 있다. 블루투스로만 폰과 통신하는 기기는 HA와 사실상 인연이 없다. BLE 도어벨 같은 제품은 영상·음성이 폰과 블루투스로 직결되고, 클라우드로는 배터리 잔량 같은 상태만 올라온다. 게이트웨이를 거쳐 상태 연동은 되더라도 그게 전부다. 기기를 살 때 앱 스크린샷만 보지 말고 "Wi-Fi로 직접 연결되는지"를 확인하자. 이 한 줄이 누군가의 주말을 지켜줄 것이다.
전력 계량형 스마트플러그가 있다면 에너지 대시보드가 이 설치의 백미가 된다. 전체 구조는 이렇다.
flowchart LR
subgraph DEV["집안 기기"]
P1["에어컨 전력 측정"]
P2["서버 전력 측정"]
C["스마트 커튼"]
D["스마트 도어락·버튼"]
end
subgraph HAC["Home Assistant 컨테이너"]
I["통합(Tuya 등) - 기기 상태 수집"]
R["recorder - 상태 이력 DB"]
E["에너지 대시보드"]
U["utility_meter - 일간/월간 합계"]
A["자동화 엔진"]
end
M["모바일 앱 - 대시보드·푸시"]
P1 -->|전력량| I
P2 -->|전력량| I
C --> I
D --> I
I --> R
R --> E
R --> U
I --> A
A -->|기기 제어| C
E --> M
A -->|푸시| M
설정 순서는 다음과 같다.
utility_meter:
aircon_energy_daily:
source: sensor.aircon_energy
cycle: daily
aircon_energy_monthly:
source: sensor.aircon_energy
cycle: monthly
utility_meter에서 배울 점 두 가지. 첫째, 이 섹션은 reload가 안 되고 재시작이 필요하다 — HA 대부분은 reload로 끝나는데 이것만 예외라 자꾸 잊게 된다. 둘째, 엔티티 ID가 슬러그화된다. 이름을 한국어로 "에어컨 콘센트 월간"이라고 지으면 ID는 sensor.aekeon_konsenteu_wolgan 같은 형태가 된다. 자동화에서 찾을 때는 표시 이름이 아니라 이 ID로 검색해야 한다.
설정 → 자동화 및 장면 → 자동화 만들기. 처음 만들 만한 세 가지 패턴이다.
시간 트리거는 정해진 시각에 발화한다. 태양 트리거는 의외로 실용적인데, "일몰 30분 전"으로 걸어두면 계절이 바뀌어도 손댈 게 없다. 상태 트리거는 가장 강력하고 가장 위험한데, 예를 들어 "메인 콘센트가 꺼지면 에어컨도 끄기"를 만든다면:
trigger:
- platform: state
entity_id: switch.main_socket
from: "on"
to: "off"
action:
- action: switch.turn_off
target:
entity_id: switch.aircon_socket
from: "on"이 빠지면 어떻게 되나. 메인 콘센트가 일시적으로 오프라인 뒤 재접속하며 "꺼짐" 상태를 보고하는 순간에도 자동화가 발화해 에어컨이 꺼진다. 상태 트리거는 전이(from→to)를 명시하는 습관이 안전사고를 막는다.
같은 시간에 여러 기기를 묶어 조작할 때(아침에 커튼 열기+조명 켜기)는 자동화를 기기별로 쪼개지 말고 하나의 자동화에 동작을 여러 줄로 넣는 것이 관리 포인트가 하나라 좋다. 조건이 기기별로 갈라질 때만 분리하면 된다.
커튼은 아침 7시에 열리고, 외출 감지로 에어컨이 꺼지고, 매달 말일엔 콘센트별 전기요금 그래프가 찍힌다. HA로 넘어온 뒤 제조사 앱을 여는 횟수가 눈에 띄게 줄었다. 도커 설치의 진짜 매력은 비용이 아니라, 같은 서버에서 돌아가는 다른 서비스(CCTV 녹화, 파일 동기화, 알림)와 한 공간에서 이어진다는 점이다. 다음 화의 Frigate가 그 첫 번째 사례다.
| 증상 | 원인 | 해결 |
|---|---|---|
| 에너지·로그 메뉴가 없다 | default_config: 누락 |
configuration.yaml 첫 줄 확인 |
| 연동했는데 기기가 안 보인다 | 기기 비활성화 상태 | 기기 페이지에서 활성화 |
| 전력 센서가 안 보인다 | 출고 때 비활성화된 센서 | 기기 페이지에서 해당 센서 활성화 |
| 프록시 뒤에서 로그인 무한 새로고침 | trusted_proxies 누락 |
http 섹션에 프록시 대역 추가 |
| 앱 푸시가 안 온다 | 외부 접속 경로 없음 | 도메인+프록시 구성 필요 |
| utility_meter 수정이 안 반영된다 | reload 미지원 | 재시작 |
서버가 이미 있다면 도커 쪽을 권한다. 백업과 이관이 디렉터리 복사로 끝나고 다른 서비스와 자유롭게 연동된다. 반대로 서버가 없고 HA만 목적이라면 HAOS가 관리가 더 편하다.
HA 자체는 로컬에서 계속 돌아간다. 다만 튀야 클라우드 경유 기기의 제어는 클라우드가 필요하다. 이 의존도를 낮추려면 Zigbee 동글 로컬 기기, local tuya 커스텀 통합 등을 단계적으로 붙이는 방법이 있다.
/config 디렉터리 통째로 백업해두면 그대로 돌아온다. 설정 → 시스템 → 백업 기능을 주기적으로 돌리고, 호스트 쪽 백업 스크립트와 이중화하면 안전하다.
서버 한 대로 충분하다 연재 목차 — 시리즈 소개 · 2화. Frigate + go2rtc · 3화. Seafile 13
2026년 기준 최신 버전, 실제 운영 서버에서 검증한 내용입니다.
| 이전 | 서버 한 대로 충분하다 — 셀프호스팅 연재를 시작하며 | 2026-09-30 | |
|---|---|---|---|
| 다음 | 2화. Frigate + go2rtc — 클라우드 CCTV 구독료 끊기 (자체 NVR 구축기) | 2026-09-30 |