홈어시스턴트 HTTPS 연동하기

홈어시스턴트(Home Assistant)를 외부에서도 안전하게 접속하기 위해 HTTPS 암호화를 적용하는 것은 이제 선택이 아닌 필수입니다. 수많은 방법 중에서도, 가장 널리 사용하고 추천하는 것이 바로 Nginx Proxy Manager(NPM) 를 이용하는 방식입니다.

오늘은 이 Nginx Proxy Manager를 도커(Docker)로 설치하고, 홈어시스턴트와 연결하여 Let’s Encrypt SSL 인증서를 자동으로 발급 및 갱신하는 가장 표준적인 방법을 안내해 드리고자 합니다

사전 준비물
#

본격적인 설치에 앞서, 아래 항목들이 반드시 준비되어 있어야 합니다.

개인 도메인
#

외부에서 접속할 나만의 주소입니다. (예: ha.mydomain.com) 무료 DDNS 서비스(예: DuckDNS)를 이용하시는게 좋습니다.

공유기 포트포워딩 설정
#

외부 인터넷에서 들어오는 웹 트래픽을 홈서버로 정확히 전달해주는 설정입니다. 공유기 관리 페이지에서 아래와 같이 설정해 주십시오.

외부(WAN) 포트 80 → 홈서버의 내부 IP 주소, 포트 80
외부(WAN) 포트 443 → 홈서버의 내부 IP 주소, 포트 443

Nginx Proxy Manager 설치
#

Docker Compose를 사용하면 설치와 관리가 매우 간편합니다. 홈서버의 적당한 위치에 docker-compose.yml 파일을 생성하고 아래 내용을 붙여넣으십시오.

version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      # Public HTTP Port
      - '80:80'
      # Public HTTPS Port
      - '443:443'
      # Admin Web Port
      - '81:81'
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Seoul
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

ports: 80번과 443번 포트는 외부 사용자의 실제 웹 트래픽을 처리하는 데 사용되고, 81번 포트는 우리가 NPM을 설정하기 위해 접속하는 관리자 페이지용입니다.
environment: PUID와 PGID는 현재 사용자와 docker container 내부의 사용자 ID를 설정합니다.
volumes: ./data와 ./letsencrypt 폴더에 모든 설정과 SSL 인증서 정보가 저장됩니다. 이 부분이 있어야 컨테이너를 재시작하거나 업데이트해도 모든 설정이 안전하게 유지됩니다.

파일을 저장한 후, 터미널에서 해당 파일이 있는 폴더로 이동하여 아래 명령어를 실행해 NPM 컨테이너를 시작합니다.

docker-compose up -d

Nginx Proxy Manager 초기 설정
#

웹 브라우저에서 http://<홈서버_IP>:81 주소로 접속합니다. (예: http://192.168.1.10:81)
아래 기본 계정 정보로 로그인합니다.
- Email: admin@example.com
- Password: changeme
로그인 직후, 보안을 위해 반드시 나타나는 안내에 따라 사용자 정보와 비밀번호를 자신만의 것으로 변경해주십시오.

프록시 호스트 및 SSL 인증서 설정
#

이제 외부 도메인 주소와 내부 홈어시스턴트를 연결하고, SSL 인증서를 발급받는 가장 중요한 단계입니다.

NPM 관리자 페이지 상단 메뉴에서 [Hosts] > [Proxy Hosts] 로 이동합니다.
[Add Proxy Host] 버튼을 클릭합니다.

NPM의 ‘Details’ 탭 설정 화면. 각 항목이 위 설명과 같이 채워져 있고, 특히 ‘Websockets support’가 활성화된 모습

Details 탭을 아래와 같이 채웁니다.
- Domain Names: 준비한 개인 도메인을 입력합니다. (예: ha.mydomain.com)
- Scheme: http
- Forward Hostname / IP: 홈어시스턴트가 설치된 홈서버의 내부 IP 주소를 입력합니다. (예: 192.168.1.10)
- Forward Port: 홈어시스턴트의 포트 번호인 8123을 입력합니다.
- Websockets support: 반드시 체크(활성화) 해야 합니다. 홈어시스턴트 UI의 상태가 실시간으로 부드럽게 업데이트되기 위해 필수적인 설정입니다.

SSL 탭으로 이동하여 아래와 같이 설정합니다.
- SSL Certificate: Request a new SSL Certificate를 선택합니다.
- Force SSL: 체크(활성화)합니다. 모든 접속을 자동으로 HTTPS로 전환하여 보안을 높입니다.
- Email Address for Let’s Encrypt: 유효한 이메일 주소를 입력합니다. 인증서 만료일이 다가올 때 알림을 받을 수 있습니다.
- I Agree to the Let's Encrypt Terms of Service를 체크(활성화)합니다.
마지막으로 [Save] 버튼을 누릅니다.

NPM이 자동으로 Let’s Encrypt를 통해 SSL 인증서를 발급받고 적용하는 과정이 진행됩니다. 잠시 후 목록의 상태(Status)가 Online으로 바뀌면 성공입니다.

도커 네트워크 대역 확인
#

Nginx Proxy Manager(NPM) 컨테이너가 어떤 네트워크에 연결되어 있는지 확인하고, 그 네트워크의 IP 대역(Subnet)을 찾아야 합니다.

NPM 컨테이너가 사용하는 네트워크 이름 찾기
#

먼저, 실행 중인 NPM 컨테이너의 정보를 확인하여 연결된 네트워크 이름을 찾습니다. docker-compose.yml 파일이 있는 폴더에서 아래 명령어를 실행하세요.

$ docker compose ps
WARN[0000] /home/user/Services/nginx-proxy-manager/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
NAME                        IMAGE                             COMMAND   SERVICE   CREATED       STATUS       PORTS
nginx-proxy-manager-app-1   jc21/nginx-proxy-manager:latest   "/init"   app       9 hours ago   Up 9 hours   0.0.0.0:80-81->80-81/tcp, [::]:80-81->80-81/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp

nginx-proxy-manager-app-1 이 현재 NPM 컨테이너의 이름입니다.

NPM 컨테이너의 이름을 확인했다면, docker inspect 명령어로 네트워크 정보를 봅니다.

docker inspect nginx-proxy-manager-app-1

출력된 결과(JSON 형식)가 매우 길게 나오는데, 그중에서 "Networks" 부분을 찾으면 아래와 같이 연결된 네트워크 이름이 보입니다. 보통 docker-compose로 만들었다면 폴더명_default 같은 이름으로 생성됩니다.

...
"Networks": { // <-- 여기를 검색합니다.
    "npm_default": {  // <-- 이 부분이 네트워크 이름입니다.
        ...
    }
}
...

네트워크의 상세 정보에서 IP 대역 확인하기
#

이제 위에서 찾은 네트워크 이름(npm_default)을 사용하여 네트워크의 상세 정보를 확인합니다.

docker network inspect npm_default

출력된 정보에서 "IPAM" (IP Address Management) 섹션을 찾으면, 우리가 원하는 "Subnet" 값이 있습니다.

[
    {
        ...
        "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": [
                {
                    "Subnet": "172.23.0.0/16",  // <-- 바로 이 값입니다!
                    "Gateway": "172.23.0.1"
                }
            ]
        },
        ...
    }
]

홈어시스턴트 설정 파일 수정
#

마지막으로 홈어시스턴트가 리버스 프록시(NPM)를 통해 들어오는 접속을 신뢰하도록 설정해야 합니다.

홈어시스턴트의 configuration.yaml 파일을 엽니다.
아래 http 설정을 추가하거나, 기존 내용이 있다면 trusted_proxies 부분을 추가합니다.

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.19.0.2/16  # NPM이 포함된 도커 네트워크 대역

trusted_proxies 설정은 “이 IP 대역에서 오는 요청은 내가 신뢰하는 Nginx Proxy Manager를 거친 것이니 믿고 받아들여라"라고 홈어시스턴트에게 알려주는 역할을 합니다. 위 예시처럼 입력하면 대부분의 도커 환경에서 문제없이 작동합니다.

configuration.yaml 파일을 저장한 후, 홈어시스턴트를 재시작합니다.

마무리하며
#

모든 설정이 끝났습니다. 이제 웹 브라우저에서 https://ha.mydomain.com 처럼 자신의 도메인으로 접속해 보십시오. 주소창에 안전함을 상징하는 자물쇠(🔒)가 표시된 홈어시스턴트 화면을 마주하실 수 있을 겁니다.

Nginx Proxy Manager를 통해 여러분의 홈서버는 더욱 안전해졌을 뿐만 아니라, 앞으로 다른 서비스를 추가하더라도 손쉽게 HTTPS를 적용할 수 있는 강력한 확장성까지 갖추게 되었습니다.

사전 준비물#

개인 도메인#

공유기 포트포워딩 설정#

Nginx Proxy Manager 설치#

Nginx Proxy Manager 초기 설정#

프록시 호스트 및 SSL 인증서 설정#

도커 네트워크 대역 확인#

NPM 컨테이너가 사용하는 네트워크 이름 찾기#

네트워크의 상세 정보에서 IP 대역 확인하기#

홈어시스턴트 설정 파일 수정#

마무리하며#