Como fazer self-host do Homepage em 2026: hosts permitidos, widgets e configuração

Existem duas versões de “executar o Homepage”: um container existe ou o serviço cumpre sua função de verdade. Apenas a segunda importa. Aqui, a comprovação consiste em carregar serviços e favoritos, chamar vários widgets ativos, testar a pesquisa e reiniciar após editar um arquivo de configuração YAML.

O Homepage cumpre esta função: ser uma página inicial com widgets ativos para serviços self-hosted. A implantação precisa preservar os componentes por trás desse comportamento; uma porta, um volume e um certificado são entradas, não o resultado.

Escolha a topologia mínima viável do Homepage

Um diagrama útil do Homepage mostra a rota pública, a porta privada 3000, o limite de estado e todos os requisitos de suporte. Marque quais setas transportam credenciais e quais representam tráfego comum de usuários. O requisito externo do Homepage é uma configuração somente leitura acompanhada das credenciais dos widgets de serviços opcionais. Teste o DNS de saída, o TLS e o comportamento do provedor sem publicar outro serviço de entrada.

Comprove o diagrama com uma ação real: carregue serviços e favoritos, chame vários widgets ativos, teste a pesquisa e reinicie após editar um arquivo de configuração YAML. A pressão mais provável vem da distribuição de chamadas dos widgets, de APIs downstream lentas, da resolução de DNS e da taxa de atualização do dashboard no navegador; monitore esse caminho em vez de tratar todas as requisições HTTP como equivalentes.

Atualize o Homepage sem fazer suposições

A primeira métrica operacional útil do Homepage é verificar se ele consegue carregar serviços e favoritos, chamar vários widgets ativos, testar a pesquisa e reiniciar após editar um arquivo de configuração YAML. Combine isso com sinais de saturação relacionados à distribuição de chamadas dos widgets, às APIs downstream lentas, à resolução de DNS e à taxa de atualização do dashboard no navegador. Uma verificação que avalia apenas o processo não deve chamar dependências dispendiosas nem reiniciar o container porque um upstream ficou temporariamente indisponível.

Trate as atualizações como alterações de dados, pois as chaves de configuração e as integrações de widgets podem mudar; por isso, valide o YAML e o comportamento do provedor antes de atualizar a imagem. Fixe as versões, ensaie o procedimento com o estado restaurado e mantenha a imagem anterior disponível até que um rollback continue sendo válido. Quando o host é rejeitado ou a indentação do YAML impede o carregamento da configuração, preserve os logs anteriores ao reinício; eles normalmente contêm a mensagem que explica a causa.

Um procedimento de aceitação de produção para o Homepage

Antes da chegada dos usuários reais, crie uma planilha de release para o Homepage. Ela deve indicar a imagem fixada, a porta 3000, a origem canônica, os caminhos persistentes e o responsável pela configuração somente leitura acompanhada das credenciais dos widgets de serviços opcionais. Anexe o resultado esperado desta transação: carregar serviços e favoritos, chamar vários widgets ativos, testar a pesquisa e reiniciar após editar um arquivo de configuração YAML.

Use a planilha após uma substituição normal e depois de uma restauração limpa. A recuperação só é aceita se os serviços, favoritos, widgets e assets personalizados retornarem e todos os widgets críticos lidarem de forma visível com falhas downstream. Colete também um breve trace de recursos que cubra a distribuição de chamadas dos widgets, as APIs downstream lentas, a resolução de DNS e a taxa de atualização do dashboard no navegador; mantenha-o junto da release para que futuras alterações de capacidade sejam comparadas com a mesma carga de trabalho.

Inclua uma falha controlada: negue temporariamente o caminho de teste usado pela configuração somente leitura acompanhada das credenciais dos widgets de serviços opcionais. Confirme que o Homepage relata o problema no limite correto, restaure a condição válida e execute novamente a transação. Isso verifica a visibilidade dos erros, não apenas o sucesso, e impede que uma interface aparentemente saudável esconda um worker, callback ou conexão com o banco de dados quebrado.

Torne a inicialização do Homepage reproduzível

Use o container como um runtime substituível, não como o local onde a verdade fica armazenada.

docker run -d \
  --name homepage \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v homepage-data:/app/config \
  -e HOMEPAGE_ALLOWED_HOSTS=home.example.com \
  ghcr.io/gethomepage/homepage:latest

Permita e verifique o caminho de saída ou do lado do cliente necessário para a configuração somente leitura acompanhada das credenciais dos widgets de serviços opcionais. Inspecione o usuário do container, os caminhos graváveis e o listener vinculado antes de expô-lo. Execute a ação completa — carregar serviços e favoritos, chamar vários widgets ativos, testar a pesquisa e reiniciar após editar um arquivo de configuração YAML — e salve a referência exata da imagem que produziu o resultado.

Separe containers substituíveis de dados duráveis

O conjunto durável de recuperação inclui arquivos de configuração, favoritos, serviços e assets personalizados. Monte /app/config antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Um volume protege os dados contra a substituição do container, mas não contra a perda do host, a exclusão acidental ou a corrupção no nível da aplicação.

Faça backups que entendam a origem dos dados: use dumps lógicos para bancos de dados ativos quando necessário e copie arquivos apenas a partir de um estado consistente. Mantenha uma cópia criptografada fora do host do Homepage. O critério de aceitação de uma restauração é específico: os serviços, favoritos, widgets e assets personalizados retornam e todos os widgets críticos lidam de forma visível com falhas downstream. O guia de backups testados com restauração explica por que o simples sucesso do job não é suficiente.

Domínios, headers de proxy e porta 3000

O navegador, o cliente da API e o Homepage precisam concordar com uma única origem. Para que isso aconteça, defina os hosts permitidos para o domínio exato e o hostname do proxy. Preserve o host e o protocolo originais, mantendo a porta 3000 indisponível como um endereço público concorrente.

O guia de troubleshooting para sites fora do ar ajuda a distinguir uma rota inacessível de uma aplicação que está respondendo. Essa distinção é importante aqui: o host é rejeitado ou a indentação do YAML impede o carregamento da configuração. Apenas o primeiro caso é corrigido com alterações no ingress; o segundo exige a inspeção dos logs, do estado ou da carga de trabalho do Homepage.

Decisões de segurança específicas do Homepage

Não herde pressupostos de segurança de um tutorial local. A preocupação específica do Homepage é fazer commit de API keys dos widgets em um repositório público. Por isso, em produção, defina os hosts permitidos com precisão e mantenha as API keys dos widgets em variáveis de ambiente ou em uma configuração respaldada por secrets, e não em um repositório público.

HOMEPAGE_ALLOWED_HOSTS controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do Homepage separadamente. Restrinja o acesso ao filesystem e à rede, proteja os endpoints de configuração e defina limites de upload, requisições ou execução em torno da distribuição de chamadas dos widgets, das APIs downstream lentas, da resolução de DNS e da taxa de atualização do dashboard no navegador.

Onde o Dockup reduz o trabalho com o Homepage

Para o Homepage, o Dockup é mais útil no limite entre uma imagem e um serviço durável. Ele mantém a rota para a porta 3000, o TLS, os valores secretos e o armazenamento associados entre substituições de containers, independentemente de o compute pertencer ao Dockup ou ao seu servidor conectado.

Finalize com conhecimento da aplicação: defina os hosts permitidos para o domínio exato e o hostname do proxy; permita e verifique a configuração somente leitura acompanhada das credenciais dos widgets de serviços opcionais; e execute esta verificação: carregue serviços e favoritos, chame vários widgets ativos, teste a pesquisa e reinicie após editar um arquivo de configuração YAML. Mantenha o resultado como uma verificação de deployment para que a próxima atualização da imagem seja avaliada pelo comportamento, e não pelo status do container.

Perguntas frequentes

O que o Homepage precisa para um deployment em produção?

Encaminhe o container do Homepage na porta 3000 por meio de uma única origem HTTPS. O requisito externo de entrega é uma configuração somente leitura acompanhada das credenciais dos widgets de serviços opcionais. Não considere o Homepage pronto até conseguir carregar serviços e favoritos, chamar vários widgets ativos, testar a pesquisa e reiniciar após editar um arquivo de configuração YAML.

Quais dados do Homepage devem fazer parte de um backup?

Persista /app/config e inclua arquivos de configuração, favoritos, serviços e assets personalizados no mesmo manifesto de recuperação. Uma restauração limpa do Homepage só é aprovada quando os serviços, favoritos, widgets e assets personalizados retornam e todos os widgets críticos lidam de forma visível com falhas downstream.

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

Use HTTPS na origem pública do Homepage e mantenha a porta 3000 na rota interna. Aplique corretamente a configuração do Homepage: defina os hosts permitidos para o domínio exato e o hostname do proxy. No Homepage, o HTTPS protege credenciais ou conteúdo do usuário durante o transporte e mantém consistente o comportamento do cliente que depende da origem.

Como testar uma atualização do Homepage?

Restaure o estado atual do Homepage em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois as chaves de configuração e as integrações de widgets podem mudar; por isso, valide o YAML e o comportamento do provedor antes de atualizar a imagem. Mantenha a imagem anterior do Homepage até entender os limites da migração de dados e do rollback.