Ubuntu 서버에 홈어시스턴트 설치하기

오늘은 스마트 홈 구축의 첫걸음이라 할 수 있는 Ubuntu Server에 홈어시스턴트(Home Assistant)를 설치하는 모든 과정을 안내해 드리고자 합니다. 이 가이드 하나만으로 설치를 완벽하게 끝내실 수 있도록, 가장 핵심적인 내용을 상세히 다루겠습니다.

차근차근 절차를 밟아나가시면, 누구나 성공적으로 자신만의 스마트 홈 허브를 구축하실 수 있을 겁니다.

시작하기 전에: Docker 준비

#

이 가이드는 시스템에 도커(Docker)가 이미 설치된 것을 전제로 합니다. 도커는 홈어시스턴트를 컨테이너 환경에서 안정적으로 구동하기 위한 필수 프로그램입니다.

만약 아직 도커를 설치하지 않으셨다면, 먼저 아래 링크의 가이드를 따라 설치를 완료하신 후 이 글의 다음 단계를 진행해 주시기 바랍니다.

홈어시스턴트 설치: 두 가지 방법 중 선택

#

이제 홈어시스턴트를 설치할 차례입니다. 아래 두 가지 방법 중 하나를 선택하여 진행하십시오.

• 방법 1: docker run - 간단하고 빠르게 컨테이너 하나를 실행하고 싶을 때 적합합니다.
• 방법 2: docker-compose - 설정 내용을 파일로 저장하여 장기적으로 관리하고 싶을 때 추천하는 방식입니다.

docker run 명령어를 직접 사용하는 방법

#

가장 기본적인 방식입니다. 한 줄의 명령어로 홈어시스턴트를 즉시 실행할 수 있습니다.

홈어시스턴트 설정 파일이 저장될 디렉터리를 생성합니다.

mkdir ~/homeassistant/config

아래의 docker run 명령어를 터미널에 입력하여 홈어시스턴트를 실행합니다.

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

• –name homeassistant: 컨테이너의 이름을 ‘homeassistant’로 지정합니다.
• -v ~/homeassistant_config:/config: 호스트의 ~/homeassistant_config 디렉터리를 컨테이너의 /config에 연결하여 설정을 영구적으로 보존합니다.
• -v /run/dbus:/run/dbus:ro: 호스트의 블루투스 기능을 사용할수 있도록 연동합니다.
• –network=host: 컨테이너가 호스트의 네트워크를 직접 사용하도록 설정하여 별도의 포트 설정 없이 8123 포트로 접근하게 합니다.

docker-compose 파일을 사용하는 방법 (권장)

#

설정 내용을 docker-compose.yml 파일로 저장하여 관리하므로, 재설치나 수정, 업데이트가 매우 편리합니다.

홈어시스턴트 관리를 위한 디렉터리를 만들고 그 안으로 이동합니다.

mkdir ~/homeassistant
cd ~/homeassistant

nano 와 같은 편집기로 docker-compose.yml 파일을 생성하고 아래 내용을 작성합니다.

nano docker-compose.yml

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

• docker run 명령어의 모든 옵션이 YAML 형식으로 보기 쉽게 정리되어 있습니다.
• volumes의 ./config:/config는 docker-compose.yml 파일이 위치한 곳에 config 폴더를 만들어 설정을 저장하겠다는 의미입니다.

작성이 완료되었다면, 아래 명령어로 홈어시스턴트를 실행합니다. -d는 백그라운드 실행 옵션입니다.

docker compose up -d

홈어시스턴트 초기 설정

#

위 두 가지 방법 중 어떤 것을 선택했더라도, 초기 설정 과정은 동일합니다.

같은 네트워크에 있는 PC나 스마트폰의 웹 브라우저를 열고 주소창에 다음 주소를 입력합니다.

• http://[우분투 서버의 IP 주소]:8123
• (예: http://192.168.0.10:8123)

화면에 나타나는 안내에 따라 관리자 계정을 생성하고, 집 위치 등 기본적인 정보를 입력하여 설정을 완료합니다.

접속이 되지 않는다면? 방화벽 설정

#

우분투 서버에서 UFW(Uncomplicated Firewall)와 같은 방화벽을 사용하고 있다면, 외부에서 홈어시스턴트의 웹 인터페이스(8123 포트)에 접근할 수 있도록 허용 규칙을 추가해야 합니다.

sudo ufw allow 8123/tcp

마무리하며

#

이것으로 우분투 서버에 도커를 이용한 홈어시스턴트 설치가 모두 완료되었습니다. docker run의 간편함과 docker-compose의 관리 용이성 사이에서 독자분께 더 적합한 방법을 선택하여 성공적으로 설치를 마치셨기를 바랍니다.

참조

• Home Assistant 공식 설치 가이드 (www.home-assistant.io/installation/linux )