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

Docker에서 Localtonet 실행하기

이 페이지 도움받기
이 페이지의 내용 섹션 12개
  1. 시작하기 전에
  2. 단계
  3. 이미지 가져오기
  4. 토큰으로 컨테이너 시작하기
  5. 터널 만들고 시작하기
  6. 컨테이너가 실행되는 방식
  7. 백그라운드에서 실행하고 자동으로 다시 시작하기
  8. 토큰을 전달하는 방법
  9. Docker Compose
  10. 컨테이너에서 내 서비스에 접근하기
  11. 로그 읽기
  12. 업데이트
  13. 레지스트리에 접근할 수 없는 호스트용 이미지 아카이브
  14. 문제 해결
  15. 관련 페이지

공식 이미지 localtonet/localtonet은 컨테이너에서 Localtonet 클라이언트를 실행합니다. AuthToken을 전달한 다음 평소처럼 대시보드에서 터널을 만들고 시작하세요.

시작하기 전에 #

  • 64비트 호스트의 Docker. 이미지는 linux/amd64와 linux/arm64용으로 배포되며, Docker가 호스트에 맞는 것을 선택합니다. 32비트 ARM 기기에서는 대신 Linux 빌드를 사용하세요.
  • 내 토큰에서 발급한 AuthToken. 컨테이너마다 토큰을 따로 사용하세요. 같은 토큰으로 두 번째 클라이언트가 연결되면 첫 번째 클라이언트의 연결이 끊어집니다.

단계 #

  1. 이미지 가져오기 #

    먼저 pull을 하면 호스트에 남아 있는 이전 이미지가 아니라 최신 버전을 실행할 수 있습니다.

    Bash
    docker pull localtonet/localtonet

    이미지는 Docker Hub에 있습니다. latest 외에도 특정 릴리스에 고정하고 싶을 때 쓸 수 있는 버전별 태그가 Docker Hub에 나열되어 있습니다.

  2. 토큰으로 컨테이너 시작하기 #

    이미지 이름 뒤의 모든 내용은 Localtonet 클라이언트에 전달됩니다. <YOUR_TOKEN>을 내 AuthToken으로 바꾸세요.

    Bash
    docker run localtonet/localtonet --authtoken <YOUR_TOKEN>

    컨테이너는 연결 상태를 출력하며 포그라운드에서 계속 실행됩니다. 중지하려면 Ctrl + C를 누르세요.

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

    대시보드를 열고 컨테이너에 전달한 토큰으로 터널을 만든 다음 시작을 선택하세요. 입력 양식은 빠른 시작에서 볼 수 있습니다. 컨테이너 안에서는 127.0.0.1의 의미가 다르므로 로컬 IP 주소를 입력하기 전에 컨테이너에서 내 서비스에 접근하기를 읽어 보세요.

컨테이너가 실행되는 방식 #

이미지는 클라이언트를 헤드리스 모드로 시작합니다. 데스크톱 클라이언트와 비교하면 세 가지가 달라집니다.

  • 질문을 하지 않습니다. 토큰이 없거나 형식이 올바르지 않으면 컨테이너가 오류를 출력하고 종료 코드 2로 종료됩니다.
  • 실시간 상태 표 대신 일반 로그 줄을 기록하며, -it로 시작해도 마찬가지입니다.
  • 토큰을 저장하지 않습니다. 이미지에는 볼륨이 선언되어 있지 않으므로 컨테이너를 만들 때마다 명령줄, 환경 변수 또는 파일로 토큰을 전달하세요.

터널은 컨테이너에서 구성하지 않습니다. 대시보드에서 터널을 만들고, 시작하고, 중지하면 컨테이너가 연결을 통해 이를 가져옵니다.

백그라운드에서 실행하고 자동으로 다시 시작하기 #

분리 실행을 위해 -d를, 재부팅이나 충돌 후 Docker가 컨테이너를 다시 시작하도록 재시작 정책을 사용하세요.

Bash
docker run -d \
  --name localtonet \
  --restart unless-stopped \
  localtonet/localtonet --authtoken <YOUR_TOKEN>

평소와 같은 Docker 명령으로 관리합니다.

명령어기능
docker ps실행 중인 컨테이너를 나열합니다.
docker logs -f localtonet클라이언트의 로그를 실시간으로 따라갑니다.
docker stop localtonet클라이언트를 중지합니다. 해당 터널은 오프라인이 됩니다.
docker start localtonet같은 토큰으로 다시 시작합니다.
docker rm -f localtonet컨테이너를 제거합니다.

토큰을 전달하는 방법 #

명령줄의 토큰은 docker inspect와 호스트의 프로세스 목록에 표시됩니다. 이미지는 환경 변수나 파일에서도 토큰을 읽을 수 있습니다.

소스사용 방법참고
--authtoken <YOUR_TOKEN>이미지 이름 뒤에 오는 인수.가장 간단합니다. LOCALTONET_AUTH_TOKEN보다 우선합니다.
LOCALTONET_AUTH_TOKEN토큰을 담고 있는 환경 변수.--authtoken 인수가 없을 때 사용됩니다.
LOCALTONET_AUTH_TOKEN_FILE토큰만 들어 있는 파일의 컨테이너 내부 경로를 담고 있는 환경 변수.토큰 파일은 직접 전달한 토큰보다 항상 우선합니다. --authtoken-file <PATH> 인수도 같은 역할을 합니다.

이미지가 LOCALTONET_HEADLESS=1을 직접 설정하므로 따로 설정할 필요가 없습니다.

토큰 파일을 사용하면 토큰이 컨테이너 정의에 들어가지 않으며, 읽기 전용으로 마운트하면 됩니다.

Bash
printf '%s' '<YOUR_TOKEN>' > auth-token
chmod 600 auth-token

docker run -d \
  --name localtonet \
  --restart unless-stopped \
  -e LOCALTONET_AUTH_TOKEN_FILE=/run/secrets/localtonet_auth_token \
  -v "$(pwd)/auth-token:/run/secrets/localtonet_auth_token:ro" \
  localtonet/localtonet

컨테이너를 시작하기 전에 토큰 파일을 만드세요. 파일이 없으면 Docker가 같은 이름의 디렉터리를 만들고, 클라이언트는 그 디렉터리에서 토큰을 읽을 수 없습니다.

연결하지 않고 토큰 소스를 확인하려면 --check-config를 추가하세요. 클라이언트가 토큰이 있고 형식이 올바른지(33자, 공백 없음) 확인한 다음 Localtonet headless configuration OK.를 출력하고 종료합니다. 토큰이 유효한지 서버에 확인하지는 않습니다.

Bash
docker run --rm \
  -e LOCALTONET_AUTH_TOKEN_FILE=/run/secrets/localtonet_auth_token \
  -v "$(pwd)/auth-token:/run/secrets/localtonet_auth_token:ro" \
  localtonet/localtonet --check-config

Docker Compose #

같은 설정을 Compose 파일로 작성한 예입니다. 토큰을 compose.yaml 옆의 auth-token이라는 파일에 넣으세요.

compose.yaml
services:
  localtonet:
    image: localtonet/localtonet
    restart: unless-stopped
    environment:
      LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
    volumes:
      - ./auth-token:/run/secrets/localtonet_auth_token:ro
Bash
docker compose up -d
docker compose logs -f localtonet

공개하려는 서비스가 Linux 호스트의 같은 Compose 프로젝트에 있다면 그 포트를 호스트에 게시하고 Localtonet 컨테이너를 호스트 네트워킹으로 실행하세요. 터널의 로컬 주소는 IP 주소여야 하므로 web 같은 Compose 서비스 이름은 사용할 수 없습니다.

compose.yaml
services:
  web:
    image: nginx
    ports:
      - "8080:80"

  localtonet:
    image: localtonet/localtonet
    restart: unless-stopped
    network_mode: host
    environment:
      LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
    volumes:
      - ./auth-token:/run/secrets/localtonet_auth_token:ro

이 예시에서는 터널의 로컬 주소를 127.0.0.1, 로컬 포트를 8080으로 설정하세요.

NAS나 Home Assistant용 템플릿은 NAS와 Home Assistant 페이지에 준비되어 있습니다.

컨테이너에서 내 서비스에 접근하기 #

터널의 로컬 IP 주소와 로컬 포트는 클라이언트에게 서비스의 위치를 알려 줍니다. 클라이언트는 컨테이너 안에서 연결하는데, 컨테이너 안의 127.0.0.1은 내 컴퓨터가 아니라 컨테이너 자신입니다. IP 주소를 입력하세요. 클라이언트는 host.docker.internal, Compose 서비스 이름, 컨테이너 이름 같은 Docker 이름을 조회하지 않습니다. 서비스가 실행되는 위치에 맞는 값을 사용하세요.

서비스가 실행되는 위치입력할 로컬 주소추가로 필요한 것
Docker 호스트, Linux127.0.0.1컨테이너를 --network host로 시작하세요(Compose에서는 network_mode: host). 그러면 컨테이너가 호스트의 네트워크를 공유합니다.
Docker 호스트, 호스트 네트워킹 없이(Windows나 macOS의 Docker Desktop 포함)호스트의 LAN IP 주소(예: 192.168.1.10)서비스는 127.0.0.1뿐 아니라 컨테이너가 접근할 수 있는 주소에서 수신 대기해야 하며, 호스트의 방화벽이 연결을 허용해야 합니다.
다른 컨테이너Linux에서 --network host를 쓰면 127.0.0.1, 그렇지 않으면 호스트의 LAN IP 주소해당 컨테이너의 포트를 호스트에 게시하고(-p, Compose에서는 ports) 게시된 포트를 터널의 로컬 포트로 사용하세요.
네트워크의 다른 기기그 기기의 LAN IP 주소(예: 192.168.1.20)없음.
Linux, 호스트의 서비스
docker run -d \
  --name localtonet \
  --restart unless-stopped \
  --network host \
  localtonet/localtonet --authtoken <YOUR_TOKEN>

기존 터널의 주소는 터널 설정의 로컬 주소에서 변경할 수 있습니다. 설정 참조를 참고하세요.

로그 읽기 #

docker logs -f localtonet은 변경이 있을 때마다 한 줄씩 보여 줍니다. 첫 줄을 제외한 모든 줄은 타임스탬프로 시작합니다.

줄의미
Localtonet - headless log클라이언트가 시작되었습니다.
Connection: …Localtonet과의 연결 상태입니다. 상태가 바뀌면 새 줄이 나타납니다.
AuthTokenName: …컨테이너가 로그인한 토큰의 이름이며, 내 토큰에 표시되는 이름과 같습니다.
OPEN …, ADDED …이 토큰의 터널입니다. 클라이언트가 시작될 때 이미 있는 터널에는 OPEN이, 나중에 생기는 터널에는 ADDED가 사용됩니다.
STATUS …터널의 상태가 바뀌었습니다.
CLOSED …이 클라이언트에서 터널이 제거되었습니다.
Authentication failed: AuthToken was rejected.Localtonet이 토큰을 받아들이지 않았습니다.

토큰 자체는 로그에 기록되지 않습니다.

업데이트 #

이미지를 다시 pull하고 컨테이너를 다시 만드세요.

Bash
docker pull localtonet/localtonet
docker rm -f localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>

Compose를 사용한다면 docker compose pull을 실행한 다음 docker compose up -d를 실행하세요. 항상 최신 이미지로 시작하려면 docker run에 --pull always를 추가하세요.

레지스트리에 접근할 수 없는 호스트용 이미지 아카이브 #

호스트가 Docker Hub에 접근할 수 없다면 다른 컴퓨터에서 이미지를 TAR 아카이브로 다운로드한 뒤 복사해 와서 불러오세요.

아키텍처아카이브
AMD64localtonet-docker-amd64.tar
ARM64localtonet-docker-arm64.tar
Bash
docker load --input localtonet-docker-amd64.tar

docker load는 불러온 내용을 출력합니다. 이름 대신 이미지 ID가 출력되면 실행하기 전에 이미지에 이름을 지정하세요.

Bash
docker tag <IMAGE_ID> localtonet/localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>

문제 해결 #

컨테이너가 "Invalid Localtonet headless configuration" 오류와 함께 곧바로 종료됩니다

전체 메시지는 Invalid Localtonet headless configuration. Check the token file or environment settings.입니다. 클라이언트가 사용할 수 있는 토큰을 찾지 못했습니다. 아무것도 전달되지 않았거나, 값이 33자가 아니거나, 중간에 공백이나 줄바꿈이 있거나, 토큰 파일 경로가 컨테이너에 없는 경우입니다. 토큰 파일을 마운트했다면 호스트에서 그것이 디렉터리가 아니라 파일인지 확인하세요. 재시작 정책이 있으면 토큰을 고칠 때까지 컨테이너가 계속 다시 시작되므로 docker logs localtonet을 읽어 보세요.

로그에 "Authentication failed: AuthToken was rejected."가 표시됩니다

토큰 형식은 올바르지만 Localtonet이 받아들이지 않습니다. 내 토큰에서 다시 복사한 다음 컨테이너를 다시 만드세요.

터널은 시작되었는데 공개 주소로 내 서비스에 접근할 수 없습니다

터널의 로컬 주소를 확인하세요. 127.0.0.1은 Linux에서 --network host를 쓸 때만 동작합니다. 그렇지 않으면 호스트의 LAN IP 주소를 사용하세요. host.docker.internal 같은 이름이나 다른 컨테이너의 이름은 이 필드에서 동작하지 않으며, 자세한 내용은 컨테이너에서 내 서비스에 접근하기에서 설명합니다.

컨테이너의 연결이 계속 끊어집니다

다른 클라이언트가 같은 토큰을 사용하고 있지 않은지 확인하세요. 같은 토큰으로 두 번째 클라이언트가 연결되면 첫 번째 클라이언트의 연결이 끊어집니다. 내 토큰에서 컨테이너나 기기마다 토큰을 하나씩 만드세요.

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

지원