본문으로 건너뛰기
Localtonet Localtonet 대시보드

NAS와 Home Assistant에서 Localtonet 실행

설정 템플릿 AMD64 및 ARM64

이 페이지 도움받기
이 페이지의 내용 섹션 7개
  1. 템플릿 소개
  2. 템플릿이 아닌 것
  3. 시작하기 전에
  4. Docker Compose로 NAS 설정하기
  5. ZIP을 풀고 nas 폴더를 NAS로 복사
  6. 토큰 파일 만들기
  7. compose.yaml은 그대로 두기
  8. 프로젝트 시작
  9. 터널 만들고 시작하기
  10. Compose 템플릿의 동작
  11. Home Assistant OS 또는 Supervised 설정하기
  12. 앱 폴더 복사
  13. 앱 스토어를 새로 고치고 Localtonet 설치
  14. 토큰을 입력하고 앱 시작
  15. 터널 만들고 시작하기
  16. 서비스에 접근하기
  17. 로그 및 업데이트
  18. 관련 페이지

Localtonet은 Docker를 지원하는 NAS와 Home Assistant에서 Localtonet 클라이언트를 컨테이너로 실행하는 배포 템플릿을 제공합니다. AuthToken을 추가하고 컨테이너를 시작한 다음, 대시보드에서 터널을 관리하세요.

템플릿 소개 #

다운로드 파일은 템플릿 두 개, 총 파일 다섯 개가 들어 있는 작은 ZIP 아카이브입니다.

템플릿사용 대상파일수정할 내용
NAS / Docker Compose(nas 폴더)Synology Container Manager, QNAP Container Station, Docker를 실행하는 그 밖의 NAS, Home Assistant Container 또는 Core 호스트nas/compose.yaml 및 nas/auth-token.example토큰만 수정합니다. auth-token.example을 auth-token으로 복사하고 DUMMY_AUTH_TOKEN을 사용자의 AuthToken으로 바꾸세요. compose.yaml은 그대로 두세요.
Home Assistant 앱(home-assistant 폴더)Home Assistant OS 및 Home Assistant Supervisedhome-assistant/localtonet/config.json(로컬 앱의 정의이며, 예전에는 add-on이라고 불렀습니다) 및 home-assistant/repository.json파일에서 수정할 것은 없습니다. 앱을 설치한 뒤 Home Assistant에서 토큰을 입력합니다. 로컬 설치에서는 repository.json을 사용하지 않습니다.

다섯 번째 파일인 README.txt는 이 페이지의 단계를 간단한 텍스트로 정리한 것입니다.

두 템플릿 모두 Docker 페이지에서 설명하는 방식으로, 프롬프트 없이 컨테이너에서 Localtonet 클라이언트를 실행합니다. AMD64(Intel 및 AMD 프로세서)와 ARM64용으로 만들어졌습니다. 시작하기 전에 NAS의 프로세서를 확인하세요. 32비트 ARM NAS에서는 실행할 수 없습니다.

템플릿이 아닌 것 #

  • Synology SPK나 QNAP QPKG 패키지가 아닙니다. Synology Package Center나 QNAP App Center에는 아무것도 나타나지 않습니다.
  • Home Assistant 템플릿은 공식 Home Assistant 스토어에 등록된 항목이 아닙니다. 로컬 앱으로 설치합니다.
  • 컨테이너 이미지는 포함되어 있지 않습니다. 기기가 템플릿에 지정된 이미지 docker.io/localtonet/localtonet을 가져오며, 이는 Docker Hub에 있는 Docker 페이지의 이미지입니다.
  • VPN 인터페이스에 필요한 권한을 컨테이너에 부여하지 않습니다. 템플릿은 터널용이며 VPN 기능은 포함되지 않습니다.

시작하기 전에 #

  • Docker와 Docker Compose를 지원하는 NAS 또는 Home Assistant OS / Supervised.
  • 내 토큰의 AuthToken. 다른 기기에서 사용하지 않는 토큰을 사용하세요. 같은 토큰으로 두 번째 클라이언트가 연결하면 첫 번째 클라이언트의 연결이 끊어집니다.
  • 템플릿 ZIP. 다운로드 파일은 이 페이지 끝의 목록과 다운로드 페이지에 있습니다.

Docker Compose로 NAS 설정하기 #

  1. ZIP을 풀고 nas 폴더를 NAS로 복사 #

    컴퓨터에서 아카이브를 풉니다. nas 폴더를 컨테이너 관리자가 사용할 수 있는 NAS의 공유 폴더로 복사하세요.

  2. 토큰 파일 만들기 #

    nas 폴더에서 auth-token.example을 auth-token으로 복사합니다. auth-token을 열어 DUMMY_AUTH_TOKEN을 사용자의 AuthToken으로 바꾸세요. 한 줄에 토큰만 넣고 파일에 다른 내용은 넣지 마세요.

    토큰 파일을 비공개로 유지하세요. NAS에서 본인 계정만 접근하도록 제한하고, 다른 사람이 읽을 수 있는 공유 폴더나 동기화 폴더에 두지 마세요. 토큰이 있으면 Localtonet 클라이언트가 이 기기로 연결할 수 있습니다.

    파일은 컨테이너를 시작하기 전에 존재해야 합니다. 파일이 없으면 Docker가 auth-token이라는 이름의 디렉터리를 대신 만들고, 컨테이너는 그 안에서 토큰을 읽을 수 없습니다.

  3. compose.yaml은 그대로 두기 #

    compose.yaml을 수정할 필요는 없습니다. image: 줄에는 Localtonet 이미지와 이 ZIP이 만들어진 버전이 지정되어 있습니다. 예: docker.io/localtonet/localtonet:8.6.0. 나머지 줄은 Compose 템플릿의 동작에서 설명합니다.

  4. 프로젝트 시작 #

    컨테이너 관리자에서 compose.yaml을 프로젝트로 가져와 시작하세요.

    • Synology: Container Manager에서 nas 폴더와 그 안의 compose.yaml로 프로젝트를 만듭니다.
    • QNAP: Container Station에서 compose.yaml로 애플리케이션을 만듭니다. 이 파일은 Compose 파일 기준 상대 경로로 ./auth-token을 마운트하므로 토큰 파일이 그 경로에 있어야 합니다.
    • 셸이 있는 모든 Docker 호스트: nas 디렉터리에서 아래 명령을 실행하세요.
    Bash
    docker compose up -d

    정확한 화면은 NAS 모델과 버전에 따라 다릅니다. Compose 파일로 프로젝트를 만드는 방법은 제조사 설명서를 따르세요.

  5. 터널 만들고 시작하기 #

    컨테이너가 실행되면 대시보드를 열어 파일에 넣은 토큰으로 터널을 만들고 시작을 선택하세요. 빠른 시작과 같은 방식입니다.

Compose 템플릿의 동작 #

아래가 파일 전체입니다. image: 줄 끝의 태그는 ZIP이 만들어진 Localtonet 버전이며, 8.6.0은 예시입니다.

nas/compose.yaml
services:
  localtonet:
    image: "docker.io/localtonet/localtonet:8.6.0"
    restart: unless-stopped
    network_mode: host
    environment:
      LOCALTONET_HEADLESS: "1"
      LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
    volumes:
      - ./auth-token:/run/secrets/localtonet_auth_token:ro
설정기능
imageLocaltonet 이미지 docker.io/localtonet/localtonet와 실행할 버전입니다. 태그는 다른 버전으로 옮길 때만 바꾸세요. 로그 및 업데이트를 참고하세요.
restart: unless-stopped재부팅이나 충돌 후 Docker가 컨테이너를 다시 시작합니다. 직접 중지한 경우는 제외됩니다.
network_mode: host컨테이너가 NAS의 네트워크를 공유합니다. 그러면 터널이 NAS 자체의 서비스에는 127.0.0.1로, LAN의 다른 기기에는 LAN 주소로 접근할 수 있습니다. 이를 위해 Linux 호스트 네트워킹이 필요합니다.
LOCALTONET_HEADLESS프롬프트 없이, 일반 로그 줄로 클라이언트를 실행합니다.
LOCALTONET_AUTH_TOKEN_FILE클라이언트가 토큰을 읽는 파일의 컨테이너 내부 경로입니다.
volumesauth-token 파일을 해당 경로에 읽기 전용으로 마운트합니다.

Home Assistant OS 또는 Supervised 설정하기 #

Home Assistant OS와 Supervised는 Supervisor를 통해 앱을 실행합니다. 템플릿은 기기에 복사하는 로컬 앱입니다.

  1. 앱 폴더 복사 #

    ZIP을 풉니다. home-assistant/localtonet 폴더를 Home Assistant의 로컬 앱 디렉터리로 복사해 /addons/localtonet이 되게 하세요. 이 폴더에는 config.json 파일 하나가 들어 있습니다. 수정하지 마세요. 이 파일에는 앱 이름 Localtonet, 이미지 docker.io/localtonet/localtonet, 이 ZIP이 만들어진 버전이 지정되어 있으며, authtoken 옵션은 나중에 채우도록 비워져 있습니다.

  2. 앱 스토어를 새로 고치고 Localtonet 설치 #

    Home Assistant에서 앱 스토어를 새로 고쳐 로컬 앱이 검색되게 한 다음 Localtonet을 설치하세요.

  3. 토큰을 입력하고 앱 시작 #

    앱의 Configuration 페이지를 열고 authtoken 옵션에 AuthToken을 입력한 다음 앱을 시작하세요. Home Assistant는 이 값을 비밀번호처럼 숨깁니다. 이후 앱은 Home Assistant와 함께 자동으로 시작됩니다.

  4. 터널 만들고 시작하기 #

    대시보드에서 해당 토큰으로 터널을 만들고 시작을 선택하세요. Home Assistant 자체를 공개하려면 127.0.0.1과 Home Assistant가 수신 대기하는 포트로 HTTP 터널을 만드세요. Home Assistant의 기본 포트는 8123입니다. Home Assistant에는 프록시를 거쳐 들어오는 요청에 대한 자체 설정이 있으며, 요청이 거부되면 Home Assistant HTTP 문서를 참고하세요.

앱은 호스트 네트워킹을 사용하므로 Home Assistant와 네트워크의 다른 기기에 직접 접근합니다. Home Assistant 아키텍처 amd64와 aarch64를 지원합니다.

Home Assistant Container와 Core에는 Supervisor가 없으므로 앱을 설치할 수 없습니다. 이러한 설치에서는 Docker 호스트에서 NAS / Docker Compose 템플릿을 대신 사용하세요.

home-assistant/repository.json 파일은 복사하는 폴더 밖에 있으며 로컬 설치에는 필요하지 않습니다. 저장소 URL과 유지 관리자에 대한 자리 표시 값(DUMMY)이 들어 있으니 무시하세요.

서비스에 접근하기 #

두 템플릿 모두 호스트 네트워킹을 사용합니다. 터널의 로컬 IP 주소 필드에는 다음과 같이 입력합니다.

  • 127.0.0.1은 NAS 또는 Home Assistant 호스트 자신입니다. NAS 웹 인터페이스, Home Assistant 등 그 기기의 모든 서비스에 사용하며, 해당 서비스가 수신 대기하는 포트와 함께 입력하세요.
  • 192.168.1.20 같은 LAN 주소는 네트워크의 다른 기기에 접근합니다.

시작된 터널은 인터넷에서 접근할 수 있습니다. NAS 로그인 페이지나 Home Assistant를 공개하기 전에 서비스 자체에 강력한 비밀번호와 2단계 인증을 설정하고, 접근 제어 페이지의 옵션도 고려하세요.

로그 및 업데이트 #

컨테이너는 일반 로그 줄을 기록합니다. 연결 상태, 로그인한 토큰의 이름, 터널이 추가되거나 상태가 바뀌거나 제거될 때마다 한 줄씩 남습니다. 컨테이너 관리자의 로그 보기, Home Assistant의 앱 Log 탭, 또는 다음 명령으로 확인하세요.

Bash
docker compose logs -f localtonet

Invalid Localtonet headless configuration. Check the token file or environment settings. 줄은 클라이언트가 사용할 수 있는 토큰을 찾지 못했다는 뜻입니다. 토큰 파일이 없거나 비어 있거나, 아직 DUMMY_AUTH_TOKEN이 들어 있거나, 토큰이 33자가 아닌 경우입니다. Authentication failed: AuthToken was rejected.는 토큰 형식은 올바르지만 Localtonet이 수락하지 않는다는 뜻입니다.

템플릿 ZIP은 각각 하나의 Localtonet 버전용으로 만들어집니다. Compose 파일은 image: 줄의 태그에, Home Assistant 앱은 config.json의 version 필드에 버전을 고정합니다. NAS를 새 버전으로 옮기려면 태그를 해당 이미지에 대해 Docker Hub에 나열된 버전으로 바꾸고(Docker 참고) docker compose up -d를 다시 실행하세요(또는 컨테이너 관리자에서 프로젝트를 업데이트하세요). auth-token 파일은 그대로 둡니다.

NAS 및 Home Assistant

Synology Container Manager, QNAP Container Station 및 기타 Docker 지원 NAS 기기용 Docker Compose 템플릿과, OS / Supervised용 Home Assistant 앱 템플릿입니다. AMD64 및 ARM64를 지원합니다.

이것은 설정 템플릿이며 SPK / QPKG 설치 파일이나 공식 Home Assistant 스토어 등록 앱이 아닙니다. 레지스트리에 일치하는 Docker 이미지가 있어야 합니다. Home Assistant Container / Core 사용자는 Compose 템플릿을 사용할 수 있습니다.

NAS 또는 Home Assistant 설정
  1. ZIP의 압축을 풀고 README.txt를 읽으세요.
  2. NAS의 경우 nas/auth-token.example을 nas/auth-token으로 복사하고 AuthToken을 입력하세요. 이 파일은 비공개로 유지하세요.
  3. nas/compose.yaml의 이미지 태그를 확인한 다음 프로젝트로 가져오거나 nas 디렉터리에서 docker compose up -d를 실행하세요.
  4. Home Assistant OS / Supervised의 경우 README의 로컬 앱 설치 안내를 따르고 앱 설정에 토큰을 입력하세요.

템플릿은 LAN 접근을 위해 Linux 호스트 네트워킹을 사용합니다. VPN 권한은 활성화하지 않습니다.

이 페이지에 도움이 필요하신가요? 커뮤니티에 질문하거나 지원 티켓을 만들어 주세요.

지원