ATENÇÃO!
Já faz algum tempo que o tipo de instalação do Home Assistant denominada de Supervisionada vem apresentando problemas e instabilidades. É fato que existem requisitos rigorosos que precisam ser atendidos para que se consiga uma instalação funcional. Todavia, não tem sido suficiente. Usuários brasileiros e estrangeiros relatam que mesmo seguindo todas as recomendações o resultado tem sido instalações repletas de avisos de falta de integridade dosistema. Isso quando os containers sobem, haja vista que os problemas começam quando da instalação da lista de dependências, entre elas o NetworkManager, que sobrescreve as configurações de rede originais do Debian e impossibilita, inclusive, a resolução de nomes (DNS), o que por sua vez impede a instalação dos demais pacotes, como o docker. Existem algumas estratégias (gambiarras!?) usadas para tentar resolver esses problemas, inclusive já inseridas no tutorial abaixo, mas nenhuma se mostrou suficiente e definitiva até o momento em que escrevo esse alerta. Sendo assim, deixo claro que a observância literal dos passos descritos abaixo não garante uma instalação estável e livre de problemas. Se decidir prosseguir com esse modelo de instalação é ciente de que poderá precisar pesquisar e solucionar os problemas que aparecerem.
Home Assistant no Debian 12 sem a interface gráfica!
Nesse tutorial abordarei a instalação do Home Assistant Supervised no Debian 12 sem interface gráfica. Existem muitos tutoriais bons (em texto e vídeo) que demonstram esse tipo de instalação. No entanto, são poucos os que estão na nossa língua nativa. Para muitos/as isso não é um problema, mas o é para tantos/as outros/as, principalmente os/as que estão iniciando nesse universo da automação residencial com Home Assistant e Debian.
Sendo assim, esse tutorial objetiva demonstrar, de forma clara, objetiva, detalhada e com muitos exemplos em texto e imagens (muitas imagens) como instalar o Home Assistant Supervised no Debian 12. Dessa maneira, espero contribuir para que os/as recém chegados ao Home Assistant não desistam no primeiro degrau, que é a instalação do ecossistema. É nessa perspectiva que esse tutorial se insere.
PRÉ-REQUISITOS:
a) Hardware para instalação do Debian (a partir de 2gb de Ram e 32gb de armazenamento);
b) Imagem netinstall do Debian 12 - Baixe aqui;
c) Pendrive de 4GB (para gravação da imagem do Debian 12) - Para gravar a imagem no pendrive você pode utilizar o Rufus, disponível para Windows, o Ventoy, disponível para Windows e Linux ou o Balena Etcher, disponível para Windows, Linux e Mac;
d) Internet cabeada.
e) Outro computador (com Windows, Linux ou Mac) para acessar o servidor via SSH.
Esse tutorial está dividido em duas partes. A primeira aborda a instalação do Sistema Operacional Debian 12 (para a realização do tutorial utilizamos uma máquina virtual no VirtualBox, mas os procedimentos se aplicam perfeitamente a máquinas físicas) e a segunda aborda a instalação do Home Assistant Supervised de acordo com a documentação oficial disponível aqui e aqui.
1ª PARTE: Instalação do Debian 12
INSTALANDO O DEBIAN 12 BOOKWORM - CLIQUE PARA MOSTRAR/OCULTAR O CONTEÚDO
A primeira coisa a ser feita é instalar o Debian 11 no dispositivo que servirá de servidor para o Home Assistant (PC, Notebook, Mini PC)
-
Dê boot na máquina com o pendrive de instalação do Debian 11. Na tela do Grub selecione Advanced Options… e depois Enter;
-
Na tela seguinte selecione a opção …Graphical expert install e depois Enter. Sugiro a utilização dessa opção por ela permitir maior controle sobre o que estamos instalando;
-
Selecione Choose language e tecle Enter;
-
Selecione Português do Brasil e tecle Enter;
-
Selecione Brasil e tecle Enter;
-
Selecione pt_BR.UTF-8 e tecle Enter;
-
Na tela seguinte não selecione nada e clique em Continuar;
-
Selecione a opção Selecione o teclado e tecle Enter;
-
Selecione Português Brasileiro e tecle Enter;
-
Selecione Detectar e montar mídia de instalação e tecle Enter;
-
Selecione os módulos disponíveis e tecle Enter. Se a mídia foi corretamente detectada tecle Enter novamente;
-
Selecione Carregar componentes a partir da mídia de instalação;
-
Na tela seguinte marque os componentes que necessitar e tecle Enter. Para o propósito desse tutorial não precisaremos de nenhum componente adicional;
-
Selecione Detectar hardware de rede e tecle Enter. Em seguida selecione Configurar rede e tecle Enter novamente;
-
Como o objetivo desse tutorial é simplificar a instalação do Home Assistant Supervised marcaremos para que o instalador configure a rede automaticamente. Será atribuído um endereço de IP via DHCP, o qual pode sofrer alteração quando a máquina for reiniciada. Mais à frente no tutorial é explicado como fixar o IP após a finalização da instalação do Home Assistant;
-
Se a configuração automática foi bem sucedida a tela seguinte será a de inserção do nome da máquina. No nosso teste usamos o nome zaratustra (personagem criado pelo filósofo Nietzsche). Coloque um nome para identificar a sua máquina e tecle Enter;
-
No domínio você pode colocar “home.lan”;
-
Selecione Usuários e senhas e tecle Enter. Na tela seguinte marque Sim para habilitar senhas sombra e Não para não permitir login como root (isso fará com que o instalador faça a instalação do sudo e configure o usuário criado durante a instalação já com privilégios administrativos). Faremos a habilitação do root após a finalização da instalação do sistema;
-
Insira o nome completo do usuário e tecle Enter. No nosso exemplo usamos apenas george, mas pode usar qualquer nome;
-
Crie um nome para o seu usuário (no nosso exemplo foi apenas george também. Em seguida crie uma senha forte e continue (a senha que usamos aqui foi apenas para fins didáticos, ou seja, nunca use senhas tão simples e previsíveis);
-
Selecione Configure o relógio e tecle Enter. Na tela seguinte marque Sim e continue. Na sequência não altere nada e tecle Enter novamente. Selecione o fuso horário da sua região e continue;
-
Selecione Detectar discos e tecle Enter. Em seguida selecione Particionar discos e continue;
-
Na tela de particionamento há várias opções, mas se você não tem conhecimento em particionamento ou não tem necessidade de fazer um particionamento mais complexo selecione a opção Assistido - usar o disco inteiro;
-
Selecione o disco desejado para fazer a instalação. Se tiver mais de um disco na máquina eles serão listados;
-
Se você não tem necessidade de ter várias partições a primeira opção já vai atender muito bem ao tipo de utilização que temos em mente para o nosso servidor. Selecione para manter todos os arquivos numa única participação e tecle Enter;
-
Selecione Finalizar o particionamento e escrever as mudanças no disco e tecle Enter. Em seguida marque Sim e tecle Enter para escrever as mudanças no disco;
-
Selecione Instalar o sistema básico e tecle Enter;
-
Selecione a primeira opção;
-
Selecione a opção genérico, para incluir todos os drivers. Isso pode ser útil na utilização de periféricos, bluetooth, etc;
-
Selecione Configurar o gerenciador de pacotes. Na tela seguinte marque Não para que não seja lida outra mídia;
-
Em Usar um espelho de rede marque Sim;
-
No tipo de protocolo selecione http e continue;
-
Selecione Brasil para o País do espelho do repositório Debian;
-
Selecione o espelho deb.debian.org;
-
Se você não vai usar Proxy deixe em branco e continue;
-
Aqui marcamos se queremos habilitar os repositórios não livres no Debian. Isso permite instalar softwares que não fazem parte nativamente da distribuição Debian, os quais podem ter inclusive licenças proprietárias. Aqui deixaremos marcado como Sim;
-
Deixaremos os repositórios fonte desativados, mas se considerar que precisa deles pode habilitá-los;
-
Esse passo é muito importante. Selecione os serviços de atualização que você deseja habilitar no Debian. Indicamos marcar as duas primeiras opções para receber atualizações de segurança e atualizações do sistema. Se você pretende usar softwares do repositório backports (terá que inserir o repositório na lista de repositórios) selecione também a terceira opção;
-
Na tela seguinte selecione Selecionar e instalar software e tecle Enter. Em seguida marque se deseja instalar as atualizações de forma automática ou não. No nosso exemplo deixamos sem atualização automática, o que obriga a verificar manualmente, de tempos em tempos, se existe alguma atualização disponível. Para tanto basta rodar o comando sudo apt update && sudo apt upgrade -y;
-
Se quiser ajudar os desenvolvedores do Debian com a coleta não intrusiva de dados sobre a utilização de pacotes marque Sim;
-
Esse é um passo muito importante, pois é aqui onde definimos o quão leve e otimizado será o sistema do nosso servidor. Como não precisaremos de uma interface gráfica nativa no nosso servidor instalaremos apenas o Servidor SSH (para acessar a máquina remotamente de outro computador) e os utilitários de sistema padrão;
-
Na tela seguinte selecione Instalar o carregador de inicialização GRUB e continue. Na sequência selecione o disco para a instalação do GRUB;
-
Em seguida selecione Finalizar a instalação;
-
Na tela seguinte marque Sim para confirmar que o relógio do sistema está configurado para o padrão UTC;
-
Finalmente chegamos ao final da instalação. Se tudo correu bem será exibida a mensagem Instalação completada;
-
Tecle Enter para continuar e o sistema será inicializado;
-
Se durante a instalação você habilitou os repositórios non-free é interessante a instalação dos pacotes firmware-linux com o comando abaixo:
apt install firmware-linux firmware-linux-free firmware-linux-nonfree
2ª PARTE: Instalação do Home Assistant Supervised
Considerando que o Debian já foi instalado e iniciado corretamente agora faremos a instalação do Home Assistant com Supervisor. É muito importante ficar atento a todos os passos e tentar entender o processo de instalação.
1 - Ao inicializar o Debian será mostrada uma tela com o nome atribuído à máquina e a opção de login, onde você deverá inserir o usuário criado durante a instalação do Debian. Após dar Enter aparecerá o campo password, onde você deve inserir a senha criada para o seu usuário. No nosso exemplo criamos o usuário homeassistant e a senha 123 (é sempre recomendado usar uma senha forte, aqui é apenas para finalidade de teste). Na sequência limpe o terminal digitando o comando clear seguido de Enter;
ATENÇÃO: Durante a instalação do Debian optamos por não criar a conta de root, mas para que a instalação ocorra sem problemas será necessário criar essa conta. Para tanto basta digitar o comando abaixo logo após fazer login com o seu usuário:
sudo passwd root
Após rodar esse comando será necessário inserir a senha do seu usuário. Em seguida será necessário criar uma senha para o root. Feito isso você terá um usuário root com senha.
2 - Agora vamos identificar o nosso IP para acessar a máquina remotamente via protocolo SSH, sem a necessidade de usar monitor e teclado na máquina que hospedará o Home Assistant. Para fazer o acesso podemos usar algum aplicativo de conexão remota, como o puTTY (para Windows, disponível aqui), o PowerShell e/ou CMD do Windows ou o emulador de terminal de uma distribuição Linux. Para verificar o IP digite o comando abaixo:
hostname -I
3 - Sabendo o IP agora podemos abrir o aplicativo puTTY (o PowerShell ou o terminal Linux) e digitar no campo IP address . Em seguida clique em Open;
4 - Na tela seguinte clique em Accept;
5 - Agora digite o nome de usuário e a senha criados na instalação do Debian. A partir daqui utilizaremos apenas o terminal remoto através do puTTY;
6 - Limpe o terminal com o comando clear e depois digite o comando abaixo para logar como root (digite a senha de root criada no passo 1);
su -
7 - Antes de prosseguir com a instalação do Home Assistant com Supervisor vamos verificar se existem atualizações no sistema com o comando abaixo:
apt update && apt upgrade && apt autoremove -y
8 - Para se certificar de que não houve erros durante a atualização dos pacotes vamos rodar o comando abaixo:
apt --fix-broken install
9 - Agora precisamos instalar os pacotes necessários para a correta instalação do Home Assistant. A lista de pacotes recomendados pela documentação oficial pode ser conferida aqui. Rode os comandos atualizados abaixo para instalar:
LEIA COM ATENÇÃO!
A lista de dependências do HomeAssistant Supervised é frequentemente atualizada pela equipe de desenvolvimento. Assim, é recomendável verificar de tempos em tempos se alguma nova dependência foi introduzida na lista. Caso perceba que existem dependências novas (que não estavam presentes na data da instalação do homeassistant) basta rodar o comando abaixo como root (su -). Instalar as nova dependências garante que o homeassistant continue funcionando corretamente e sem bugs críticos. Além desse post, você consegue verificar as dependências do homeassistant supervised diretamente na página do GitHub (GitHub - home-assistant/supervised-installer: Installer for a generic Linux system)
apt install \
apparmor \
cifs-utils \
curl \
dbus \
jq \
libglib2.0-bin \
lsb-release \
network-manager \
nfs-common \
systemd-journal-remote \
systemd-resolved \
udisks2 \
wget -y
10 - Concluída a instalação dos pacotes precisamos adicionar o repositório do Docker na lista de repositórios do Debian. Isso vai permitir baixar o Docker com um simples comando e mantê-lo sempre atualizado. Use o comando abaixo, o qual também pode ser verificado na página oficial do Home Assistant no Github, disponível aqui:
curl -fsSL get.docker.com | sh
ATENÇÃO!
Se ao rodar o comando acima você receber uma mensagem de erro de que não é possível resolver get.docker.com (erro de DNS), siga os passos que seguem. Primeiramente rode o comando abaixo como root (#):
systemctl stop systemd-resolved
Em seguida adicione o DNS da Cloudflare (pode ser qualquer outro DNS) ao arquivo resolv.conf com o comando abaixo:
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf
Em seguinda rode o comando do Passo 10 e a instalação prosseguirá normalmente.
11 - Com a instalação do Docker concluída precisamos agora instalar o OS Agent, a ferramenta que proverá a interação entre o sistema Host (Debian) e o Home Assistant Supervised. No terminal do puTTY digite o comando abaixo para navegar até a pasta /tmp. Essa pasta guarda arquivos temporários que são apagados quando o sistema é reiniciado. Como vamos baixar alguns arquivos de instaladores não é uma boa prática baixar em qualquer lugar do sistema:
cd /tmp
12 - Estando dentro do diretório /tmp vamos baixar o software Os Agent na sua última versão:
curl https://api.github.com/repos/home-assistant/os-agent/releases \
| grep browser_download_url \
| grep 'x86_64[.]deb' \
| head -n 1 \
| cut -d '"' -f 4 \
| wget -qi -
O comando acima baixa a última versão do software automaticamente
Fique atento/a à arquitetura da sua máquina para baixar a versão correta do OS Agent. No exemplo desse tutorial a máquina é x86_64, logo, baixamos a versão x86_64. Clique aqui para visitar a página no GitHub do Home Assistant, onde poderá conferir todas as versões disponíveis.
13 - Para instalar utilizamos o utilitário dpkg, que é um instalador de pacotes do Debian e derivados. Use o comando abaixo:
dpkg -i os-agent*linux_x86_64.deb
14 - Ainda dentro da pasta /tmp vamos baixar o instalador do Home Assistant Supervised com o comando abaixo:
wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb
Para mais informações sobre a instalação do Home Assistant Supervisionado no Debian confira a documentação disponível aqui.
ATENÇÃO!
Se ao rodar o comando acima você receber uma mensagem de erro de que não é possível resolver o DNS, rode o utilitário nmtui:
nmtui
Edite a conexão primária (geralmente a primeira da lista) marcando a opção “Conectar automaticamente”:
Salva clicando em OK e segue para o passo 15.
15 - Em seguida faça a instalação do pacote com o comando:
dpkg -i homeassistant-supervised.deb
Caso receba uma mensagem de erro ao tentar instalar o pacote .deb do Home Assistant Supervised não se desespere. Se estiver logado como root (#) digite o comando exit e tecle Enter. Em seguida faça login como root com o comando sudo -i e refaça a instalação (dpkg -i homeassistant-supervised.deb).
16 - Embora o instalador do Home Assistant recomende reiniciar a máquina para aplicação das mudanças não faremos isso agora. Primeiramente vamos verificar se os containers do Home Assistant já subiram (sete no total). Para verificar rode o comando abaixo como root ou com sudo antes:
docker ps
Importante destacar que na primeira vez demora alguns minutos para que todos os sete containers subam corretamente.
17 - Se a após esperar alguns minutos os containers não subirem volte ao terminal do Debian ou terminal de acesso remoto (do Windows, do Linux, do Mac) e execute uma ferramenta que faz parte do pacote NetworkManager. A ferramenta em questão é a nmtui, que é uma interface de usuário em texto que auxilia na configuração de rede. Nós vamos utiliza-la para verificar se o Supervisor do Home Assistant ativou a conexão de rede. Selecione a segunda opção Ativar uma conexão e tecle Enter:
18 - Selecione a conexão que começa com Supervisor e verifique se do lado direito aparece como Ativar ou como Desativar. Se aparecer Desativar significa que ela já está ativa. Nesse caso é só voltar teclando Esc:
19 - Esse é um passo muito importante para garantir que tudo vai funcionar bem após o reboot da máquina. Na tela inicial do nmtui selecione a primeira opção
Editar uma conexão. Depois selecione a conexão que começa com Supervisor e tecle Enter. Para garantir que a rede suba normalmente quando a máquina reiniciar navegue com a tecla Tab até a opção Conectar automaticamente e a marque teclando a tecla de Espaço no teclado (se estiver marcada ignore esse passo):
Caso não queira fixar o IP pelo nmtui você já pode reiniciar a máquina para aplicar as mudanças, conforme o instalador do Home Assistant sugeriu. Nesse caso só se atente para verificar se o IP não mudou após o reboot. Você pode verificar no terminal do Debian com o comando “hostname -I”, sem as aspas. Logo abaixo você pode ter uma ideia d ecomo fixar o IP pelo nmtui e pela própria interface do Home Assistant (em breve).
Fixando IP e DNS pelo nmtui
20 - Agora que já garantimos que a rede vai funcionar normalmente podemos fixar o endereço IP pelo nmtui. No terminal do Debian, como root, digite:
nmtui
21 - Tecle Enter na opção Editar uma conexão e em seguida Enter novamente para editar a conexão selecionada:
22 - Navegue com a tecla Tab até a opção CONFIGURAÇÃO IPv4 e altere de Automático para Manual:
23 - Em seguida navegue até a opção Exibir e tecle Enter para mostrar as opções. Em Endereços adicione o IP que quer fixar. Recomendo usar o que já está em uso na máquina (verifique com o comando hostname -I no terminal do Debian. Em Gateway adicione o endereço padrão da sua rede (pode verificar essa informação pelo roteador). Em Servidores DNS adicione pelo menos dois, o local, que é o mesmo gateway da sua rede (no meu caso foi o 192.168.0.1), e o do Google, que é 8.8.8.8. Terminada a configuração clique em OK para confirmar:
(Será necessário reiniciar a máquina para aplicar as mudanças e pronto, você estará com IP fixo no seu Debian/Home Assistant e ainda preveniu problemas com servidores DNS ao adicionar um servidor local e o do Google. Mas antes de reiniciar volte na tela inicial do nmtui e verifique se a conexão está ativa clicando em)
24 - Após o reboot você poderá acessar o Home Assistant adicionando :8123 ao final do endereço IP que acabou de fixar. No nosso exemplo ficou assim: http://192.168.0.175:8123. Digite o endereço na barra de endereços de um navegador de internet e faça as configurações iniciais, como criar usuário, definir localização, etc.
Fixando IP e DNS pela UI do Home Assistant
25 - Para quem acha o nmtui complicado ou simplesmente prefere a prativcidade da interface gráfica é possível fixar IP e DNS pela interface de usuário do Home Assistant. Para tanto clique em Configurações >> Sistema >> Rede. Escolha a interface de rede que deseja fixar o IP (cabeada ou wireless) e selecione a opção Estático. Em Endereço IP/máscara de rede coloque o IP que deseja fixar (recomendo o que já está em uso na máquina) e a máscara de rede /24, ficando algo assim IP/24. Em Endereço do gateway coloque o gateway padrão da sua rede. E em Servidores DNS insira o o gateway da sua rede como DNS local, insira uma vírgula e um espaço e adicione um DNS externo, como o da Cloudflare (1.1.1.1) ou da Google 8.8.8.8. Feito isso clique em Salvar e está pronto.
Bom pessoal, é isso. O tutorial ficou relativamente longo, todavia muito rico em detalhes, que talvez não sejam tão interessantes para quem já tem algum conhecimento em Debian Linux ou Home Assistant, mas que certamente será de grande valia para quem está iniciando. E é especialmente para essas pessoas a quem o tutorial se destina. A motivação de escrevê-lo foi contribuir de alguma forma com aqueles e aquelas que estão iniciando no Home Assistant (e em Debian Linux) com instruções claras e exemplificadas em português brasileiro.
OBSERVAÇÃO FINAL!
Se após ter executado todas as etapas você ainda receber alguma mensagem de erro nas configurações do Home Assistant, tente os dois comandos abaixo:
dpkg-reconfigure docker-ce
dpkg-reconfigure homeassistant-supervised
Por último, ams não menos importante, reinicie a máquina na qual está fazendo a instalação.
REFERÊNCIAS
Abaixo listo algumas fontes que consultei para construir esse tutorial.
Guia de Instalação de Debian GNU/Linux
Instalação do Debian 11 Bullseye limpa passo-a-passo
Install Home Assistant Supervised
Supervised Installer - Github
OS Agent - Github
Installing Home Assistant Supervised on Debian 11
