Como fazer self-hosting do Homarr em 2026: dashboards, secrets e live tiles

Um container do Homarr pode estar verde enquanto a tarefa importante para os utilizadores está quebrada. No Homarr, essa falha oculta geralmente significa que os widgets não conseguem alcançar os serviços porque usam endereços locais do host. Este guia considera “criar um board, adicionar um service tile, configurar uma integração com credenciais e confirmar o status e a pesquisa em tempo real após um restart” como o teste de aceitação e estrutura o deployment de trás para a frente a partir desse resultado.

O Homarr tem uma função específica na stack: um dashboard pesquisável com live tiles para serviços self-hosted. Portanto, a questão em produção não é se a porta 7575 responde uma vez, mas se o estado, as dependências e o endereço público continuam alinhados depois de um restart, update e restore.

Defina primeiro o que significa sucesso para o Homarr

Não deixe que a imagem do Homarr escolha acidentalmente a arquitetura de produção. A imagem fornece um processo na porta 7575; o storage, o routing e os requisitos externos ainda precisam de ciclos de vida definidos de forma deliberada. O requisito de runtime local é ter dados persistentes da aplicação e credenciais para integrações em tempo real. Isso deve fazer parte do plano de capacidade e mounts, com um responsável e um limite mensurável.

O deployment está pronto para testes mais profundos quando consegue criar um board, adicionar um service tile, configurar uma integração com credenciais e confirmar o status e a pesquisa em tempo real após um restart. Acompanhe a transação nos logs e observe a distribuição de requests dos widgets, a latência das APIs downstream, o tamanho dos app data e o número de clientes concorrentes do dashboard. Essas observações mostram se a topologia atual isola o componente correto.

Ensaie a alteração arriscada no Homarr

Um container verde é necessário, mas não suficiente. O indicador de serviço é a conclusão bem-sucedida de “criar um board, adicionar um service tile, configurar uma integração com credenciais e confirmar o status e a pesquisa em tempo real após um restart”, enquanto os sinais de pressão mais prováveis são a distribuição de requests dos widgets, a latência das APIs downstream, o tamanho dos app data e o número de clientes concorrentes do dashboard.

O change control é importante porque as migrações de schema e a continuidade da encryption key do Homarr podem afetar as credenciais de integrações armazenadas. Preserve a imagem antiga, teste as migrações com uma cópia do estado e documente se o rollback é suportado depois da alteração do schema. Se os widgets não conseguem alcançar os serviços porque usam endereços locais do host, diagnostique o primeiro boundary que difere do ambiente funcional.

Registre um deployment do Homarr conhecido por funcionar

Não use o tráfego do primeiro utilizador como teste de aceitação do Homarr. Prepare um estado de exemplo inofensivo e execute a ação completa “criar um board, adicionar um service tile, configurar uma integração com credenciais e confirmar o status e a pesquisa em tempo real após um restart”. Registe o URL público exato, o resultado, a referência da imagem e o intervalo de logs associado à execução.

Substitua o container e repita sem reconstruir os dados. Em seguida, faça o recovery num host vazio; a condição de recovery é que os boards, utilizadores, integrações e custom assets sejam restaurados e que os widgets com credenciais voltem a conectar-se. Observe a distribuição de requests dos widgets, a latência das APIs downstream, o tamanho dos app data e o número de clientes concorrentes do dashboard em cada execução e defina um alert baseado na degradação da transação, não nas métricas de um container inativo.

Uma verificação final deve falhar de propósito: envie um input inofensivo próximo do limite de recurso ou formato associado a este boundary: os widgets não conseguem alcançar os serviços porque usam endereços locais do host. Confirme que a mensagem resultante do Homarr identifica o boundary relevante, em vez de eliminar dados ou iniciar um restart infinito. Restaure a condição válida e confirme que a mesma transação de exemplo é concluída com sucesso. Mantenha este exercício curto no release checklist.

Execute a primeira instância semelhante à de produção

O primeiro container deve ser fácil de eliminar e recriar. Mantenha os dados fora da writable layer, faça o bind da porta 7575 apenas onde o proxy possa alcançá-la e passe a configuração em runtime.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Fixe a versão da imagem depois do teste inicial. Leia o erro de startup mais antigo em vez da mensagem final de restart, verifique cada mount com docker inspect e acompanhe os logs enquanto cria um board, adiciona um service tile, configura uma integração com credenciais e confirma o status e a pesquisa em tempo real após um restart. Essa sequência distingue um comando de imagem incorreto de um problema de dependência ou permissões.

Os volumes são apenas a primeira camada de recovery

Para o Homarr, a segurança do redeploy começa pelos boards, utilizadores, integrações, secrets e custom assets. Faça o mount de /appdata antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Teste o caminho substituindo o container enquanto os dados de exemplo inofensivos ainda existem; isso revela mounts apontados uma pasta acima ou abaixo do necessário.

Em seguida, teste o disaster recovery num host vazio. Quando necessário, use uma exportação da base de dados consistente com a aplicação e confirme que os boards, utilizadores, integrações e custom assets são restaurados e que os widgets com credenciais voltam a conectar-se. O guia de backups de bases de dados testados com restore oferece um objetivo mais sólido do que simplesmente verificar se foi criado um ficheiro de archive.

Evite que o sucesso do proxy esconda uma falha da aplicação

O browser, o API client e o Homarr devem concordar com uma única origin. Para isso, defina o hostname HTTPS externo e as allowed origins. Preserve o host e o protocol originais, mantendo a porta 7575 indisponível como endereço público concorrente.

O guia de troubleshooting para sites indisponíveis ajuda a distinguir uma route inacessível de uma aplicação que responde. Essa distinção é importante aqui: os widgets não conseguem alcançar os serviços porque usam endereços locais do host. Apenas o primeiro caso é resolvido com alterações no ingress; o segundo exige a análise dos logs, do estado ou do workload do Homarr.

Encerre o acesso temporário de configuração

Um deployment seguro do Homarr começa pela remoção de autoridade. Evite alterar a encryption key depois de armazenar secrets de integrações; em vez disso, mantenha SECRET_ENCRYPTION_KEY estável, proteja a edição de boards e limite cada credencial de widget ao seu escopo.

Gere SECRET_ENCRYPTION_KEY uma única vez, mantenha-o fora do Git e preserve-o com o recovery manifest, porque alterá-lo pode invalidar o estado encriptado ou assinado da aplicação. Restrinja as rotas administrativas, use DNS privado para as dependências e reveja cada bind mount. Quando os logs forem enviados para um sistema central, filtre secrets e conteúdo privado antes que deixem o servidor.

Mova o trabalho de infraestrutura repetível para o Dockup

Para o Homarr, o Dockup é mais útil no boundary entre uma imagem e um serviço durável. Mantém a route para a porta 7575, o TLS, os valores dos secrets e o storage associados durante as substituições de containers, quer o compute pertença ao Dockup, quer ao seu servidor ligado.

Conclua com conhecimento da aplicação: defina o hostname HTTPS externo e as allowed origins; confirme o requisito local — dados persistentes da aplicação e credenciais para integrações em tempo real; e execute esta verificação: crie um board, adicione um service tile, configure uma integração com credenciais e confirme o status e a pesquisa em tempo real após um restart. Guarde o resultado como deployment check para que o próximo update da imagem seja avaliado pelo comportamento, não pelo status do container.

Perguntas frequentes

O que é necessário para um deployment do Homarr em produção?

Encaminhe o container do Homarr na porta 7575 através de uma única origin HTTPS. O requisito de runtime local é ter dados persistentes da aplicação e credenciais para integrações em tempo real. Não considere o Homarr pronto até conseguir criar um board, adicionar um service tile, configurar uma integração com credenciais e confirmar o status e a pesquisa em tempo real após um restart.

Que dados do Homarr devem fazer parte de um backup?

Persista /appdata e inclua boards, utilizadores, integrações, secrets e custom assets no mesmo recovery manifest. Um restore limpo do Homarr só é bem-sucedido quando os boards, utilizadores, integrações e custom assets são restaurados e os widgets com credenciais voltam a conectar-se.

O Homarr precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origin pública do Homarr e mantenha a porta 7575 na route interna. Aplique corretamente a configuração do Homarr: defina o hostname HTTPS externo e as allowed origins. No Homarr, o HTTPS protege as credenciais ou o conteúdo dos utilizadores durante o trânsito e mantém consistente o comportamento do cliente sensível à origin.

Como deve ser testado um upgrade do Homarr?

Restaure o estado atual do Homarr num deployment isolado, aplique a versão candidata e repita a transação de aceitação. Tenha especial atenção porque as migrações de schema e a continuidade da encryption key do Homarr podem afetar as credenciais de integrações armazenadas. Mantenha a imagem anterior do Homarr até compreender os limites da migração de dados e do rollback.