Passo a passo: Home Assistant Core no Rocky Linux 10

16 min de leitura  ·  Guia técnico

Home Assistant Core no Rocky Linux 10 é a instalação da plataforma de automação residencial em Python puro, sem interface gráfica, projetada para rodar como daemon systemd em servidores Linux. Para instalar e configurar o Home Assistant Core no Rocky Linux 10, siga este resumo:

1. Atualize o sistema e instale as dependências de compilação com Python 3.12.
2. Crie o usuário dedicado homeassistant e o diretório /srv/homeassistant.
3. Crie o ambiente virtual Python e instale o pacote homeassistant via pip.
4. Configure e habilite o serviço systemd para inicialização automática.
5. Abra a porta 8123 no firewalld e conclua o onboarding pelo navegador.
6. Opcionalmente, configure Nginx como proxy reverso com certificado TLS via Let's Encrypt.

Pré-requisitos para instalar o Home Assistant Core no Rocky Linux 10

• Servidor ou VPS com Rocky Linux 10 instalado, mínimo 2 GB de RAM e 10 GB de disco disponível.
• Acesso SSH com privilégios root ou sudo — consulte o guia Acessando servidores VPS Linux da AviraHost se necessário.
• Python 3.12 disponível nos repositórios do Rocky Linux 10 (versão mínima exigida pelo Home Assistant Core).
• Conexão com a internet para baixar pacotes via dnf e pip.
• Domínio próprio (opcional, mas necessário para proxy reverso com TLS).
• Portas 80, 443 e 8123 liberadas ou roteadas corretamente no firewall da rede.

Preparando o ambiente no Rocky Linux 10 para o Home Assistant

A instalação do servidor de automação residencial exige um conjunto específico de bibliotecas de sistema antes de qualquer pacote Python. No Rocky Linux 10, o gerenciador dnf é responsável pelas dependências de build, incluindo os cabeçalhos do Python 3.12 usados para compilar extensões nativas que muitas integrações do Home Assistant precisam.

Atualize todos os pacotes do sistema:

dnf update -y

Instale as dependências de compilação e bibliotecas necessárias:

dnf install -y python3.12 python3.12-devel python3.12-pip \
    gcc gcc-c++ make libffi-devel openssl-devel \
    libjpeg-turbo-devel zlib-devel bzip2-devel \
    readline-devel sqlite-devel wget curl git autoconf

Complete!

Crie o usuário dedicado e adicione-o ao grupo dialout para eventual acesso a portas seriais (útil para adaptadores USB em servidores dedicados):

useradd -rm homeassistant -G dialout
mkdir -p /srv/homeassistant
chown homeassistant:homeassistant /srv/homeassistant

Confirme que o usuário foi criado corretamente:

id homeassistant

uid=1001(homeassistant) gid=1001(homeassistant) groups=1001(homeassistant),20(dialout)

Instalando o Home Assistant Core com ambiente virtual Python 3.12

O passo central da instalação é criar um ambiente virtual Python isolado para o Home Assistant Core. Esse isolamento evita conflitos com outros pacotes do sistema e simplifica atualizações futuras sem risco de quebrar dependências do Rocky Linux 10.

Troque para o usuário homeassistant:

sudo -u homeassistant -H -s

Crie e ative o ambiente virtual:

python3.12 -m venv /srv/homeassistant
source /srv/homeassistant/bin/activate

O prompt muda para indicar que o venv está ativo:

(homeassistant) [homeassistant@servidor ~]$

Atualize o pip e instale o wheel antes do Home Assistant:

pip install --upgrade pip wheel setuptools

Instale o Home Assistant Core:

pip install homeassistant

Este passo compila várias extensões nativas e pode levar de 5 a 20 minutos dependendo da CPU e da conexão. O output final mostrará algo como:

Successfully installed homeassistant-2026.1.0 aiohttp-3.x.x ...

Execute o Home Assistant pela primeira vez para gerar os diretórios de configuração:

hass --open-ui

Atenção: o primeiro boot pode demorar vários minutos porque o Home Assistant baixa componentes adicionais e inicializa o banco de dados interno SQLite. Aguarde até ver no terminal:

Home Assistant initialized in X.XX seconds

Após confirmar a inicialização com sucesso, pressione Ctrl+C para interromper o processo e saia do shell do usuário homeassistant com exit. O serviço systemd criado na próxima seção substituirá essa execução manual.

Configurando o serviço systemd do Home Assistant Core no Rocky Linux 10

Gerenciar o Home Assistant como unidade systemd é essencial em ambientes de servidor. O systemd reinicia o processo automaticamente em caso de falha, registra logs via journald e garante que o serviço suba depois que a rede estiver disponível — comportamento crítico para um servidor de automação residencial que precisa estar sempre online.

Crie o arquivo de unidade systemd:

nano /etc/systemd/system/homeassistant.service

Insira o conteúdo abaixo:

[Unit]
Description=Home Assistant Core
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=homeassistant
WorkingDirectory=/srv/homeassistant
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"
RestartForceExitStatus=100
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Recarregue o systemd, habilite e inicie o serviço:

systemctl daemon-reload
systemctl enable homeassistant
systemctl start homeassistant

Verifique o status do serviço:

systemctl status homeassistant

homeassistant.service - Home Assistant Core
     Loaded: loaded (/etc/systemd/system/homeassistant.service; enabled; preset: disabled)
     Active: active (running) since Sat 2026-01-01 00:00:01 UTC

Para acompanhar logs em tempo real durante diagnósticos:

journalctl -u homeassistant -f

Abrindo a porta 8123 no firewalld e acessando o painel web

Com o serviço systemd ativo, o Home Assistant escuta na porta 8123 do servidor. No Rocky Linux 10, o firewall padrão é o firewalld, que bloqueia portas não autorizadas por padrão. Abra a porta de forma permanente:

firewall-cmd --zone=public --add-port=8123/tcp --permanent
firewall-cmd --reload

Confirme a regra aplicada:

firewall-cmd --zone=public --list-ports

8123/tcp

Acesse o assistente de configuração inicial pelo navegador:

http://IP-DO-SERVIDOR:8123

Siga o assistente de onboarding para criar a conta de administrador, definir fuso horário e localização. Após concluir, o painel principal do Home Assistant estará disponível. Para entender melhor a infraestrutura de servidor por trás dessa configuração, consulte o artigo Compreendendo o Servidor VPS: O que é e Como Funciona.

Configurando Nginx como proxy reverso com HTTPS para o Home Assistant

Expor o Home Assistant diretamente na porta 8123 sem TLS é aceitável apenas em rede local isolada. Para acesso remoto seguro, configure o Nginx como proxy reverso com certificado Let's Encrypt. Isso elimina a necessidade de expor a porta 8123 diretamente e adiciona HTTPS ao painel de automação residencial.

Instale o Nginx e o Certbot:

dnf install -y nginx python3-certbot-nginx
systemctl enable --now nginx

Crie o arquivo de configuração do virtual host:

nano /etc/nginx/conf.d/homeassistant.conf

Insira o bloco de configuração inicial para o proxy reverso:

server {
    listen 80;
    server_name homeassistant.seu-dominio.com;

    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Abra as portas HTTP e HTTPS no firewalld:

firewall-cmd --zone=public --add-service=http --permanent
firewall-cmd --zone=public --add-service=https --permanent
firewall-cmd --reload

Atenção: no Rocky Linux 10, o SELinux está ativo por padrão e bloqueia conexões de rede originadas por processos httpd. Execute o comando abaixo para autorizar o Nginx a fazer proxy para o Home Assistant:

setsebool -P httpd_can_network_connect on

Teste a configuração e recarregue o Nginx:

nginx -t
systemctl reload nginx

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Emita o certificado TLS com o Certbot:

certbot --nginx -d homeassistant.seu-dominio.com

Após a emissão, adicione as configurações de proxy confiável no arquivo de configuração do Home Assistant para que ele aceite os cabeçalhos de IP encaminhados pelo Nginx:

nano /home/homeassistant/.homeassistant/configuration.yaml

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1

Reinicie o Home Assistant para aplicar as mudanças:

systemctl restart homeassistant

Integrando o broker MQTT Mosquitto ao Home Assistant Core

O protocolo MQTT é a espinha dorsal da maioria dos dispositivos de automação residencial — sensores de temperatura, interruptores, câmeras e hubs de automação utilizam esse protocolo. Com o broker Mosquitto rodando no mesmo servidor Rocky Linux 10, o Home Assistant Core recebe e publica mensagens com baixa latência sem depender de serviços externos.

Instale e inicie o Mosquitto:

dnf install -y mosquitto mosquitto-utils
systemctl enable --now mosquitto

Verifique se o broker está escutando na porta padrão:

ss -tlnp | grep 1883

LISTEN  0  128  0.0.0.0:1883  0.0.0.0:*  users:(("mosquitto",pid=...))

Atenção: a porta 1883 não usa criptografia nativa. Abra-a no firewall apenas se o servidor estiver em rede privada ou se você configurar autenticação com usuário e senha no Mosquitto. Para ambientes expostos diretamente à internet, utilize a porta 8883 com TLS.

Para integrar o MQTT, acesse o painel em Configurações → Dispositivos e Serviços → Adicionar integração, pesquise por "MQTT" e informe 127.0.0.1 como endereço do broker e 1883 como porta. Via configuration.yaml:

mqtt:
  broker: 127.0.0.1
  port: 1883

Reinicie o serviço para aplicar a integração:

systemctl restart homeassistant

Problemas comuns e como resolver

Sintoma: o serviço homeassistant não inicia após systemctl start

Causa: o caminho do executável hass no arquivo de unidade systemd está incorreto, ou o ambiente virtual foi criado com uma versão do Python inferior a 3.12.

Solução: verifique o binário com sudo -u homeassistant /srv/homeassistant/bin/hass --version. Se retornar erro, reative o ambiente virtual, execute pip install --upgrade homeassistant e confirme a versão Python com python3 --version. Analise os logs detalhados com journalctl -u homeassistant -n 100 --no-pager.

Sintoma: painel não carrega no navegador após abrir a porta 8123

Causa: o SELinux pode estar bloqueando a porta, ou o Home Assistant ainda está no processo de inicialização — o primeiro boot pode levar até 10 minutos enquanto componentes adicionais são baixados.

Solução: confirme que o processo está ouvindo na porta com ss -tlnp | grep 8123. Se a porta não aparecer, o serviço ainda está inicializando — acompanhe os logs com journalctl -u homeassistant -f. Para verificar bloqueios do SELinux, execute ausearch -m avc -ts recent e aplique setsebool -P httpd_can_network_connect on se necessário.

Sintoma: erro "No module named homeassistant" ao iniciar pelo systemd

Causa: o systemd executa o binário hass fora do ambiente virtual, usando o Python do sistema em vez do Python do venv. Isso ocorre quando o ExecStart aponta para o caminho errado.

Solução: confirme que o parâmetro no arquivo de unidade é exatamente ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant". Após corrigir, execute systemctl daemon-reload seguido de systemctl restart homeassistant.

Sintoma: Nginx retorna 502 Bad Gateway ao usar o proxy reverso

Causa: o SELinux bloqueia conexões de rede do processo Nginx para o Home Assistant, ou o Home Assistant não está em execução no momento em que o Nginx tenta encaminhar a requisição.

Solução: verifique o status do serviço com systemctl status homeassistant e teste a conectividade local com curl -I http://127.0.0.1:8123. Se o curl retornar 200 mas o Nginx retornar 502, aplique setsebool -P httpd_can_network_connect on e recarregue com systemctl reload nginx.

Perguntas frequentes sobre Home Assistant Core no Rocky Linux

O Home Assistant Core funciona em VPS sem interface gráfica?

Sim. O Home Assistant Core é uma instalação baseada em Python que roda como daemon systemd, sem necessidade de interface gráfica ou GPU. Um VPS com Rocky Linux 10, 2 GB de RAM e acesso SSH é suficiente para rodar a plataforma e acessar o painel web pelo navegador remotamente.

Qual a diferença entre Home Assistant Core, Supervised e OS?

O Home Assistant OS é uma imagem completa para hardware dedicado como Raspberry Pi. O Supervised adiciona o supervisor de add-ons sobre um Linux existente. O Core é a instalação mínima em Python puro, ideal para servidores Linux como Rocky Linux 10, sem camadas extras — oferece mais controle mas exige configuração manual de integrações.

Qual versão do Python é necessária para o Home Assistant Core?

O Home Assistant Core exige Python 3.12 ou superior. No Rocky Linux 10, o Python disponível nos repositórios padrão pode ser inferior, sendo necessário compilar ou instalar via repositório alternativo. Sempre verifique a documentação oficial do Home Assistant para a versão mínima exigida na release atual.

Como acessar o painel do Home Assistant instalado em VPS remotamente?

Após a instalação, o Home Assistant escuta na porta 8123 do servidor. Para acessar remotamente, abra essa porta no firewall com firewalld e acesse http://IP-DO-SERVIDOR:8123 no navegador. Para maior segurança, configure um proxy reverso com Nginx e certificado TLS via Let's Encrypt, conforme demonstrado neste guia.

O Home Assistant Core suporta integrações como MQTT e Zigbee em servidor Linux?

O Home Assistant Core suporta integrações via MQTT nativamente, bastando configurar um broker como Mosquitto no mesmo servidor. Integrações que exigem hardware USB (como adaptadores Zigbee) funcionam apenas se o dispositivo USB estiver fisicamente conectado ao servidor — o que é viável em servidores dedicados, mas não em VPS virtualizados sem passthrough USB.

Conclusão

Instalar o Home Assistant Core no Rocky Linux 10 entrega um servidor de automação residencial robusto com controle total sobre dependências, segurança e atualizações. Os três pontos mais críticos para uma instalação estável são:

• Ambiente virtual Python 3.12 isolado: protege o Home Assistant de conflitos com pacotes do sistema e facilita upgrades da plataforma sem risco de regressão.
• Serviço systemd com restart automático: garante que o servidor de automação residencial suba após reinicializações e se recupere de falhas sem intervenção manual.
• Proxy reverso Nginx com TLS: elimina a exposição da porta 8123 diretamente na internet e adiciona HTTPS ao painel — indispensável para qualquer ambiente acessível remotamente.

Precisa de um servidor para rodar o Home Assistant Core?

Um VPS Linux com recursos dedicados e Rocky Linux 10 disponível para instalação imediata é a base ideal para hospedar o Home Assistant Core com estabilidade. Na AviraHost, os planos de VPS Linux incluem suporte técnico para ajudar na configuração inicial do servidor.

Conheça os planos de VPS Linux da AviraHost

Leia também

• Otimizar MariaDB 10.11 no Rocky Linux 9: tuning essencial
• Como limitar uso de CPU por usuário no Rocky Linux 9
• Solucionar erros de DNS no Bind9 no Rocky Linux 9