Cómo autoalojar Homepage en 2026: hosts permitidos, widgets y configuración

Hay dos versiones de «ejecutar Homepage»: existe un contenedor o el servicio completa su función real. Solo importa la segunda. Aquí, la prueba consiste en cargar servicios y marcadores, llamar a varios widgets en tiempo real, probar la búsqueda y reiniciar después de editar un archivo de configuración YAML.

Homepage cumple esta función: ser una página de inicio con widgets en tiempo real para servicios autoalojados. El despliegue debe conservar los elementos que hacen posible ese comportamiento; un puerto, un volumen y un certificado son entradas, no el resultado.

Elige la topología mínima viable de Homepage

Un diagrama útil de Homepage muestra la ruta pública, el puerto privado 3000, el límite de estado y todos los requisitos de soporte. Indica qué flechas transportan credenciales y cuáles corresponden al tráfico normal de los usuarios. El requisito externo de Homepage es una configuración de solo lectura junto con credenciales para los widgets opcionales de servicios. Prueba el comportamiento de DNS saliente, TLS y los proveedores sin publicar otro servicio entrante.

Demuestra el diagrama con una acción real: carga servicios y marcadores, llama a varios widgets en tiempo real, prueba la búsqueda y reinicia después de editar un archivo de configuración YAML. La presión más probable procede de la distribución de solicitudes de los widgets, las API posteriores lentas, la resolución DNS y la frecuencia de actualización del dashboard del navegador; monitoriza esa ruta en lugar de tratar todas las solicitudes HTTP como iguales.

Actualiza Homepage sin adivinar

La primera métrica operativa útil de Homepage es si puede cargar servicios y marcadores, llamar a varios widgets en tiempo real, probar la búsqueda y reiniciar después de editar un archivo de configuración YAML. Combínala con señales de saturación relacionadas con la distribución de solicitudes de los widgets, las API posteriores lentas, la resolución DNS y la frecuencia de actualización del dashboard del navegador. Una comprobación que solo valide el proceso no debería llamar a dependencias costosas ni reiniciar el contenedor porque un upstream no esté disponible temporalmente.

Trata las actualizaciones como cambios de datos porque las claves de configuración y las integraciones de widgets pueden cambiar; por eso, valida el YAML y el comportamiento de los proveedores antes de actualizar la imagen. Fija las versiones, ensaya el proceso con el estado restaurado y conserva la imagen anterior hasta que el rollback siga siendo válido. Cuando se rechaza el host o la indentación YAML impide cargar la configuración, conserva los logs anteriores al reinicio; normalmente contienen el mensaje causal.

Ejecución de aceptación de Homepage en producción

Antes de que lleguen usuarios reales, crea una hoja de verificación de la versión de Homepage. Debe indicar la imagen fijada, el puerto 3000, el origen canónico, las rutas persistentes y la persona responsable de la configuración de solo lectura junto con las credenciales para los widgets opcionales de servicios. Adjunta el resultado esperado de esta transacción: cargar servicios y marcadores, llamar a varios widgets en tiempo real, probar la búsqueda y reiniciar después de editar un archivo de configuración YAML.

Usa la hoja de verificación después de una sustitución normal y de una restauración limpia. La recuperación solo se acepta si regresan los servicios, los marcadores, los widgets y los recursos personalizados, y todos los widgets críticos gestionan de forma visible los fallos de los sistemas posteriores. Recopila también un breve registro de recursos que cubra la distribución de solicitudes de los widgets, las API posteriores lentas, la resolución DNS y la frecuencia de actualización del dashboard del navegador; guárdalo junto a la versión para comparar futuros cambios de capacidad con la misma carga de trabajo.

Incluye un fallo controlado: deniega temporalmente la ruta de prueba utilizada por la configuración de solo lectura junto con las credenciales para los widgets opcionales de servicios. Confirma que Homepage informa del problema en el límite correcto, restablece la condición válida y vuelve a ejecutar la transacción. Esto comprueba la visibilidad de los errores, no solo el éxito, y evita que una interfaz con aspecto saludable oculte un worker, callback o conexión a base de datos defectuosos.

Haz reproducible el arranque de Homepage

Usa el contenedor como un runtime reemplazable, no como la ubicación de la fuente de verdad.

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

Permite y verifica la ruta saliente o del lado del cliente necesaria para la configuración de solo lectura junto con las credenciales para los widgets opcionales de servicios. Inspecciona el usuario del contenedor, las rutas con permisos de escritura y el listener enlazado antes de exponerlo. Ejecuta la acción completa —cargar servicios y marcadores, llamar a varios widgets en tiempo real, probar la búsqueda y reiniciar después de editar un archivo de configuración YAML— y guarda la referencia exacta de la imagen que produjo el resultado.

Separa los contenedores reemplazables de los datos persistentes

El conjunto de recuperación duradero está formado por los archivos de configuración, los marcadores, los servicios y los recursos personalizados. Monta /app/config antes del bootstrap, escribe datos de muestra inofensivos y sustituye el contenedor para demostrar que esa ruta es realmente persistente. Un volumen protege los datos frente a la sustitución del contenedor, pero no frente a la pérdida del host, el borrado accidental o la corrupción a nivel de aplicación.

Haz copias de seguridad que entiendan el origen de los datos: usa volcados lógicos para las bases de datos activas cuando sea necesario y copia archivos solo desde un estado coherente. Conserva una copia cifrada fuera del host de Homepage. El criterio de aceptación de una restauración es específico: deben regresar los servicios, los marcadores, los widgets y los recursos personalizados, y todos los widgets críticos deben gestionar de forma visible los fallos de los sistemas posteriores. La guía de copias de seguridad con restauración probada explica por qué el éxito del job por sí solo no es suficiente.

Dominios, headers del proxy y el puerto 3000

El navegador, el cliente API y Homepage deben coincidir en un único origen. Para conseguirlo, configura los hosts permitidos para el dominio exacto y el hostname del proxy. Conserva el host y el protocolo originales, manteniendo el puerto 3000 inaccesible como dirección pública alternativa.

La guía para solucionar problemas cuando el sitio está caído ayuda a distinguir una ruta inaccesible de una aplicación que responde. Esa distinción es importante aquí: se rechaza el host o la indentación YAML impide cargar la configuración. Solo el primer caso se soluciona con cambios en el ingress; el segundo requiere inspeccionar los logs, el estado o la carga de trabajo de Homepage.

Decisiones de seguridad específicas de Homepage

No heredes las suposiciones de seguridad de un tutorial local. La preocupación específica de Homepage es subir las API keys de los widgets a un repositorio público. Por tanto, en producción debes configurar los hosts permitidos con precisión y mantener las API keys de los widgets en variables de entorno o en una configuración respaldada por secrets, no en un repositorio público.

HOMEPAGE_ALLOWED_HOSTS controla el comportamiento, no la confidencialidad; valida su tipo y su valor, y almacena las credenciales reales de Homepage por separado. Limita el acceso al sistema de archivos y a la red, protege los endpoints de configuración y define límites de carga, solicitudes o ejecución en torno a la distribución de solicitudes de los widgets, las API posteriores lentas, la resolución DNS y la frecuencia de actualización del dashboard del navegador.

Cómo Dockup reduce el trabajo con Homepage

Para Homepage, Dockup resulta especialmente útil en el límite entre una imagen y un servicio duradero. Mantiene asociadas la ruta al puerto 3000, TLS, los valores secretos y el almacenamiento durante las sustituciones de contenedores, tanto si el cómputo pertenece a Dockup como si pertenece a tu servidor conectado.

Termina con conocimiento de la aplicación: configura los hosts permitidos para el dominio exacto y el hostname del proxy; permite y verifica la configuración de solo lectura junto con las credenciales para los widgets opcionales de servicios; y ejecuta esta verificación: carga servicios y marcadores, llama a varios widgets en tiempo real, prueba la búsqueda y reinicia después de editar un archivo de configuración YAML. Conserva el resultado como comprobación del despliegue para que la siguiente actualización de imagen se evalúe por su comportamiento y no por el estado del contenedor.

Preguntas frecuentes

¿Qué necesita Homepage para un despliegue en producción?

Enruta el contenedor de Homepage en el puerto 3000 a través de un único origen HTTPS. El requisito externo de entrega es una configuración de solo lectura junto con credenciales para los widgets opcionales de servicios. No des Homepage por listo hasta que puedas cargar servicios y marcadores, llamar a varios widgets en tiempo real, probar la búsqueda y reiniciar después de editar un archivo de configuración YAML.

¿Qué datos de Homepage deben incluirse en una copia de seguridad?

Haz persistir /app/config e incluye los archivos de configuración, los marcadores, los servicios y los recursos personalizados en el mismo manifiesto de recuperación. Una restauración limpia de Homepage solo se considera correcta cuando regresan los servicios, los marcadores, los widgets y los recursos personalizados, y todos los widgets críticos gestionan de forma visible los fallos de los sistemas posteriores.

¿Necesita Homepage HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de Homepage y mantén el puerto 3000 en la ruta interna. Aplica correctamente la configuración de Homepage: establece los hosts permitidos para el dominio exacto y el hostname del proxy. En Homepage, HTTPS protege las credenciales o el contenido de los usuarios durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo se debe probar una actualización de Homepage?

Restaura el estado actual de Homepage en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención porque las claves de configuración y las integraciones de widgets pueden cambiar; por eso, valida el YAML y el comportamiento de los proveedores antes de actualizar la imagen. Conserva la imagen anterior de Homepage hasta comprender los límites de migración de datos y rollback.