Tutoriais de VPS
Home Assistant Container na VPS: MQTT, HTTPS e limites da LAN
Implante Home Assistant Container com Docker e Caddy. Planeje conexões domésticas, listeners MQTT e proxy confiável; proteja contas, limite histórico e teste backups coerentes antes de atualizar.

O Home Assistant coordena luzes, sensores, câmeras, energia e automações. Uma VPS atende integrações em nuvem e dispositivos remotos conectados de forma planejada, mas não enxerga automaticamente a LAN de casa. Preserve funções essenciais quando internet ou VPS falharem.
Usaremos Ubuntu 24.04, Docker Compose e Home Assistant Container.
- Container não tem Supervisor nem loja de apps/add-ons do Home Assistant OS; rode serviços auxiliares separadamente.
- Home Assistant OS inclui ambiente gerenciado e serve para máquina doméstica ou VM compatível, não para instalação dentro de um contêiner comum.
- Supervised é um método legado com requisitos rígidos do anfitrião; escolha um método atualmente suportado para novas instalações.
Zigbee/Z-Wave USB e Bluetooth normalmente precisam de equipamento em casa. APIs em nuvem e MQTT roteável podem servir na VPS. Matter não funciona remotamente por ser IP: depende de IPv6/multicast local, controlador e, em alguns casos, roteador de borda Thread.
| Recurso | Teste leve | Referência de uso contínuo |
|---|---|---|
| CPU | 2 vCPU | 2-4 vCPU |
| RAM | 2 GB | 4 GB ou mais |
| Disco | 30 GB SSD | 60 GB SSD ou mais |
| Sistema | Ubuntu 22.04/24.04 | Ubuntu 24.04 LTS |
| Domínio | ha.example.com | Subdomínio de automação |
Histórico, entidades e câmeras alteram essas necessidades. Confira free -h, df -h e docker stats; veja dimensionamento.
- Escolha por dispositivo: API em nuvem, MQTT autenticado ou ponte suportada.
- Administre por HTTPS verificado ou WireGuard/Tailscale privado.
- Mantenha 1883 privada; publique listener seguro somente quando necessário.
- Preserve vídeo na LAN ou VPN adequada, sem transformar uma VPS pequena em relay de todas as câmeras.
sudo apt update
sudo apt install -y ca-certificates curl openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/homeassistant/config
sudo chown -R "$USER":"$USER" /opt/homeassistant
cd /opt/homeassistant
Revise o instalador root ou use pacotes suportados. O grupo Docker concede acesso poderoso. Preserve /config fora do contêiner e evite edições simultâneas em configuration.yaml.
services:
homeassistant:
image: ghcr.io/home-assistant/home-assistant:stable
container_name: homeassistant
restart: unless-stopped
network_mode: host
environment:
TZ: Asia/Shanghai
volumes:
- /opt/homeassistant/config:/config
- /etc/localtime:/etc/localtime:ro
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8123/ || exit 1"]
interval: 30s
timeout: 10s
retries: 5
Asia/Shanghai é um exemplo regional: use seu fuso IANA e configure localização/fuso no cadastro. Fixe uma versão exata suportada em vez de acompanhar stable sem controle.
A rede host descobre dispositivos da rede da VPS, sem transportar broadcasts de casa. Também pode expor 8123 nas interfaces do anfitrião: restrinja listener/firewall. Sem descoberta, use bridge e 127.0.0.1:8123:8123. Confira se a imagem inclui curl para o healthcheck; uma sonda inválida não comprova falha da aplicação.
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=150 homeassistant
ssh -L 8123:127.0.0.1:8123 root@SERVER_IP
Abra http://127.0.0.1:8123 pelo túnel e crie administrador, localização e fuso horário.
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
ha.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8123
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://ha.example.com
Este ajuste corresponde a Caddy no anfitrião e aplicação em rede host:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
Mescle com a seção http existente e valide/reinicie. Na rede bridge, use o IP real do proxy visto pelo contêiner. Nunca confie em 0.0.0.0/0. Use um gateway em 80/443 e HSTS/includeSubDomains somente com HTTPS funcional. Veja Caddy.
Adicione o serviço em services e prepare diretórios persistentes:
mosquitto:
image: eclipse-mosquitto:2
container_name: mosquitto
restart: unless-stopped
ports:
- "127.0.0.1:1883:1883"
volumes:
- /opt/mosquitto/config:/mosquitto/config
- /opt/mosquitto/data:/mosquitto/data
- /opt/mosquitto/log:/mosquitto/log
O exemplo antigo precisa de uma correção: listener no loopback interno do contêiner não recebe a conexão encaminhada pelo Docker.
listener 1883 127.0.0.1
allow_anonymous false
password_file /mosquitto/config/passwd
acl_file /mosquitto/config/acl
persistence true
persistence_location /mosquitto/data/
Use listener 1883 dentro do broker e mantenha a publicação do anfitrião em 127.0.0.1 ou interface privada. Preserve allow_anonymous false, crie passwd com mosquitto_passwd e ACL restrita por dispositivo. -c serve apenas para arquivo novo, pois sobrescreve o existente. Dê ao Home Assistant os tópicos necessários de estado/comando/descoberta, sem compartilhar essa conta com todos os dispositivos. Configure leitura/escrita para o usuário da imagem.
- Home Assistant em rede host conecta a 127.0.0.1:1883; DNS de serviços Docker pertence à rede bridge compartilhada.
- Dispositivos domésticos não alcançam loopback da VPS; use VPN/listener privado ou túnel apropriado.
- MQTT em redes não confiáveis precisa de TLS; senha não criptografa tráfego.
- Confira DNS, rotas VPN, TCP, ACL e tópicos antes de alterar configurações; não habilite acesso anônimo.
- Use integrações em nuvem suportadas com HTTPS de saída.
- Mantenha MQTT/Zigbee2MQTT ou ponte suportada em casa e conecte à VPS.
- Roteie IP por WireGuard/Tailscale.
- Configure multicast explicitamente e com alcance restrito quando necessário; uma rota de sub-rede não transporta mDNS/SSDP sozinha.
São opções, sem classificação universal de confiabilidade. Para rádios USB, Bluetooth e câmeras/Matter muito locais, equipamento em casa costuma ser mais prático.
Comece com um sensor e uma lâmpada:
- Confira tempo de atualização.
- Verifique condições e fuso.
- Teste desconexão/reconexão.
- Procure erros de autenticação e loops.
- Meça crescimento do histórico.
SQLite é o recorder padrão. Reduza entidades/retenção antes de externalizar; use apenas banco suportado pela versão e com backup próprio. Guarde vídeo em NVR ou armazenamento dedicado, não em /config.
- Ative MFA e permissões suportadas; ocultar dashboard não isola entidades.
- Feche portas públicas desnecessárias, especialmente 8123/MQTT; exponha 80/443 somente se necessário.
- Proíba MQTT anônimo e separe contas por dispositivo.
- Proteja chaves permanentes de nuvem fora de código exposto.
- Restrinja o painel à VPN se esse for o desenho; Caddy público também precisa de controle de acesso.
- Revise falhas de login e IPs inesperados.
- Revise origem e permissões de integrações personalizadas.
- Não publique endereço de casa, URLs de câmeras ou tokens.
Teste WebSocket e conexões longas, evitando cache CDN de respostas autenticadas.
/config reúne automações, credenciais, usuários, integrações e normalmente histórico SQLite. O comando abaixo exige primeiro um estado consistente de banco/configuração:
mkdir -p /opt/homeassistant/backups
tar -czf /opt/homeassistant/backups/homeassistant-$(date +%F).tgz -C /opt/homeassistant config
Para cópia de arquivos, é mais seguro parar o contêiner:
docker compose stop
tar -czf /opt/homeassistant/backups/homeassistant-safe-$(date +%F).tgz -C /opt/homeassistant config
docker compose start
Salve também Compose, configuração/credenciais/dados MQTT e banco externo quando existir. Criptografe cópias externas e preserve a chave de recuperação dos backups criptografados. Restaure a mesma versão exata e teste login, integrações, automações, MQTT e histórico. Evite que um teste acione dispositivos reais. Veja recuperação.
docker image inspect ghcr.io/home-assistant/home-assistant:stable --format '{{.Id}}' > /opt/homeassistant/backups/image-id.txt
cp compose.yml /opt/homeassistant/backups/compose-$(date +%F).yml
docker compose pull
docker compose up -d
docker compose logs --tail=200 homeassistant
O ID da imagem não guarda, sozinho, uma imagem recuperável fora da VPS. Registre tag/digest imutável e preserve acesso; leia notas e teste integrações. Se banco/configuração migrou, reverta com backup correspondente. Não siga latest automaticamente.
docker compose ps
docker compose logs --tail=200 homeassistant
sudo journalctl -u caddy -n 100 --no-pager
ss -lntp | grep -E ':8123|:80|:443'
Confira listener 8123, upstream, proxy confiável, logs, permissões e memória.
Confira limite de rede, ponte doméstica, conta em nuvem, rotas VPN e multicast. Uma ponte local costuma ser mais simples de manter que encaminhar broadcasts para a VPS.
Examine logs, atualizações de entidades, fuso, triggers duplicados e mensagens retained MQTT. Consultar a cada segundo não conserta dispositivo offline e pode sobrecarregá-lo.
- Domínio, HTTPS, MFA e proxy verificados.
- Limites Container/OS/Supervised compreendidos.
- MQTT autenticado e listeners administrativos privados.
- Cada dispositivo tem caminho em nuvem/VPN/ponte funcional.
- Configuração, Compose, serviços e chaves com backup externo.
- Recuperação separada e segura testada.
- Imagem, migração e reversão documentadas.
Planeje dispositivos e rede antes de mover automações. A VPS complementa a rede doméstica, sem substituir rádios físicos ou descoberta local.