Execute o Localtonet no Docker
Nesta página 12 seções
- Antes de começar
- Passos
- Baixe a imagem
- Inicie o contêiner com seu token
- Crie e inicie um túnel
- Como o contêiner é executado
- Execute em segundo plano e reinicie automaticamente
- Maneiras de informar o token
- Docker Compose
- Alcance seu serviço a partir do contêiner
- Leia o log
- Atualização
- Arquivos de imagem para hosts sem acesso ao registro
- Solução de problemas
- Páginas relacionadas
A imagem oficial localtonet/localtonet executa o cliente do Localtonet em um contêiner. Informe seu AuthToken e depois crie e inicie túneis no painel, como de costume.
Antes de começar #
- Docker em um host de 64 bits. A imagem é publicada para
linux/amd64elinux/arm64, e o Docker escolhe a que corresponde ao seu host. Para um dispositivo ARM de 32 bits, use a versão para Linux. - Um AuthToken de Meus tokens. Dê a cada contêiner o seu próprio token: quando um segundo cliente se conecta com o mesmo token, o primeiro é desconectado.
Passos #
-
Baixe a imagem #
Baixar primeiro garante que você execute a versão atual e não uma imagem mais antiga que ainda esteja no host.
Bashdocker pull localtonet/localtonetA imagem está no Docker Hub. Além de
latest, o Docker Hub lista uma tag para cada versão, caso você queira fixar uma versão. -
Inicie o contêiner com seu token #
Tudo o que vem depois do nome da imagem é repassado ao cliente do Localtonet. Substitua
<YOUR_TOKEN>pelo seu AuthToken.Bashdocker run localtonet/localtonet --authtoken <YOUR_TOKEN>O contêiner exibe o estado da conexão e permanece em primeiro plano. Pressione Ctrl + C para pará-lo.
-
Crie e inicie um túnel #
Abra o painel, crie um túnel com o token que você deu ao contêiner e selecione Iniciar. O Início rápido mostra o formulário. Leia Alcance seu serviço a partir do contêiner antes de preencher o Endereço IP local, porque
127.0.0.1significa algo diferente dentro de um contêiner.
Como o contêiner é executado #
A imagem inicia o cliente em modo headless. Isso muda três coisas em comparação com o cliente em um desktop:
- Ele nunca faz perguntas. Se o token estiver ausente ou malformado, o contêiner exibe um erro e termina com o código 2.
- Ele grava linhas de log simples em vez da tabela de status ao vivo, também quando você o inicia com
-it. - Ele não salva o token. A imagem não declara volumes, então informe o token toda vez que um contêiner for criado: na linha de comando, em uma variável de ambiente ou como um arquivo.
Os túneis não são configurados no contêiner. Você os cria, inicia e para no painel, e o contêiner os recebe pela conexão dele.
Execute em segundo plano e reinicie automaticamente #
Use -d para executar em segundo plano e uma política de reinício, para que o Docker inicie o contêiner de novo após uma reinicialização ou uma falha:
docker run -d \
--name localtonet \
--restart unless-stopped \
localtonet/localtonet --authtoken <YOUR_TOKEN>Gerencie-o com os comandos habituais do Docker:
| Comando | O que faz |
|---|---|
docker ps | Lista os contêineres em execução. |
docker logs -f localtonet | Acompanha o log do cliente. |
docker stop localtonet | Para o cliente. Os túneis dele ficam offline. |
docker start localtonet | Inicia-o de novo com o mesmo token. |
docker rm -f localtonet | Remove o contêiner. |
Maneiras de informar o token #
Um token na linha de comando fica visível em docker inspect e na lista de processos do host. A imagem também lê o token do ambiente ou de um arquivo:
| Origem | Como usar | Observações |
|---|---|---|
--authtoken <YOUR_TOKEN> | Argumento após o nome da imagem. | O mais simples. Tem prioridade sobre LOCALTONET_AUTH_TOKEN. |
LOCALTONET_AUTH_TOKEN | Variável de ambiente que contém o token. | Usada quando nenhum argumento --authtoken é informado. |
LOCALTONET_AUTH_TOKEN_FILE | Variável de ambiente que contém o caminho, dentro do contêiner, de um arquivo que tem somente o token. | Um arquivo de token sempre tem prioridade sobre um token informado diretamente. O argumento --authtoken-file <PATH> faz o mesmo. |
A própria imagem define LOCALTONET_HEADLESS=1. Você não precisa defini-la.
Com um arquivo de token, mantenha o token fora da definição do contêiner e monte-o como somente leitura:
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/localtonetCrie o arquivo de token antes de iniciar o contêiner. Se o arquivo não existir, o Docker cria um diretório com esse nome e o cliente não consegue ler um token dele.
Para verificar uma origem de token sem se conectar, adicione --check-config. O cliente verifica se o token está presente e bem formado (33 caracteres, sem espaços), exibe Localtonet headless configuration OK. e termina. Ele não pergunta ao servidor se o token é válido.
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-configDocker Compose #
A mesma configuração como um arquivo Compose. Coloque o token em um arquivo chamado auth-token ao lado de 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:rodocker compose up -d
docker compose logs -f localtonetQuando o serviço que você quer publicar está no mesmo projeto Compose em um host Linux, publique a porta dele no host e execute o contêiner do Localtonet com rede do host. O endereço local do túnel precisa ser um endereço IP, portanto um nome de serviço do Compose como web não pode ser usado nele:
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:roPara este exemplo, defina o endereço local do túnel como 127.0.0.1 e a porta local como 8080.
Para um NAS ou o Home Assistant, há modelos prontos na página NAS e Home Assistant.
Alcance seu serviço a partir do contêiner #
O Endereço IP local e a Porta local do túnel dizem ao cliente onde seu serviço está. O cliente se conecta de dentro do contêiner, onde 127.0.0.1 é o próprio contêiner e não a sua máquina. Informe um endereço IP: o cliente não resolve nomes do Docker como host.docker.internal, o nome de um serviço do Compose ou o nome de um contêiner. Use o valor que corresponde ao local onde o serviço é executado:
| Onde o serviço é executado | Endereço local a informar | O que mais é necessário |
|---|---|---|
| No host do Docker, Linux | 127.0.0.1 | Inicie o contêiner com --network host (Compose: network_mode: host). O contêiner passa a compartilhar a rede do host. |
| No host do Docker, sem rede do host (inclusive o Docker Desktop no Windows ou no macOS) | O endereço IP da LAN do host, por exemplo 192.168.1.10 | O serviço deve escutar em um endereço que o contêiner consiga alcançar, e não apenas em 127.0.0.1, e o firewall do host deve permitir a conexão. |
| Em outro contêiner | 127.0.0.1 com --network host no Linux; caso contrário, o endereço IP da LAN do host | Publique a porta desse contêiner no host (-p; Compose: ports) e use a porta publicada como porta local do túnel. |
| Em outro dispositivo da sua rede | O endereço IP da LAN desse dispositivo, por exemplo 192.168.1.20 | Nada. |
docker run -d \
--name localtonet \
--restart unless-stopped \
--network host \
localtonet/localtonet --authtoken <YOUR_TOKEN>Você pode alterar o endereço de um túnel existente nas configurações dele, em Endereço local. Veja a referência de configurações.
Leia o log #
docker logs -f localtonet mostra uma linha por mudança. Toda linha depois da primeira começa com um carimbo de data e hora:
| Linha | Significado |
|---|---|
Localtonet - headless log | O cliente foi iniciado. |
Connection: … | O estado da conexão com o Localtonet. Uma nova linha aparece quando ele muda. |
AuthTokenName: … | O nome do token com o qual o contêiner se conectou, como mostrado em Meus tokens. |
OPEN …, ADDED … | Um túnel deste token. OPEN é usado para túneis que existem quando o cliente inicia, ADDED para túneis que aparecem depois. |
STATUS … | O status de um túnel mudou. |
CLOSED … | Um túnel foi removido deste cliente. |
Authentication failed: AuthToken was rejected. | O Localtonet não aceitou o token. |
O token em si nunca é gravado no log.
Atualização #
Baixe a imagem de novo e recrie o contêiner:
docker pull localtonet/localtonet
docker rm -f localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>Com o Compose, execute docker compose pull e depois docker compose up -d. Para sempre começar da imagem mais recente, adicione --pull always ao docker run.
Arquivos de imagem para hosts sem acesso ao registro #
Se o host não alcança o Docker Hub, baixe a imagem como um arquivo TAR em outra máquina, copie-o e carregue-o:
| Arquitetura | Arquivo |
|---|---|
| AMD64 | localtonet-docker-amd64.tar |
| ARM64 | localtonet-docker-arm64.tar |
docker load --input localtonet-docker-amd64.tarO docker load exibe o que foi carregado. Se ele exibir um ID de imagem em vez de um nome, dê um nome à imagem antes de executá-la:
docker tag <IMAGE_ID> localtonet/localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>Solução de problemas #
O contêiner termina logo de início com "Invalid Localtonet headless configuration"
A mensagem completa é Invalid Localtonet headless configuration. Check the token file or environment settings. O cliente não encontrou nenhum token utilizável: nada foi informado, o valor não tem 33 caracteres, contém um espaço ou quebra de linha no meio, ou o caminho do arquivo de token não existe no contêiner. Se você monta um arquivo de token, verifique no host se ele é um arquivo e não um diretório. Com uma política de reinício, o contêiner continua reiniciando até você corrigir o token, então leia docker logs localtonet.
O log mostra "Authentication failed: AuthToken was rejected."
O token está bem formado, mas o Localtonet não o aceita. Copie-o de novo de Meus tokens e recrie o contêiner.
O túnel está iniciado, mas o endereço público não chega ao meu serviço
Verifique o endereço local do túnel. 127.0.0.1 só funciona com --network host no Linux. Caso contrário, use o endereço IP da LAN do host. Um nome como host.docker.internal ou o nome de outro contêiner não funciona neste campo, como descrito em Alcance seu serviço a partir do contêiner.
O contêiner perde a conexão o tempo todo
Verifique se nenhum outro cliente usa o mesmo token. Um segundo cliente que se conecta com o token desconecta o primeiro. Crie um token por contêiner ou dispositivo em Meus tokens.