Homepage convierte la maraña de servicios de tu homelab en una única portada limpia, rápida y ordenada, con enlaces, estado en directo y widgets de cada aplicación. En esta guía lo levantas con un solo docker-compose.yml, entiendes su configuración por archivos YAML, lo dejas escuchando en el puerto 3000 y consigues que descubra tus contenedores automáticamente leyendo sus etiquetas. Ojo: hablamos del panel de servicios Homepage (gethomepage), no de la página de inicio de un navegador. La misma explicación está disponible en inglés.

Puntos clave

  • Homepage es un panel de aplicaciones de código abierto, escrito en Next.js y React, con más de 31 500 estrellas en GitHub y licencia GPL-3.0.
  • Es totalmente estático: se genera en el arranque, no monta base de datos y su huella de memoria es mínima, por lo que vuela incluso en una Raspberry Pi.
  • Escucha en el puerto 3000 y trae integraciones para más de 100 servicios, con widgets que muestran datos en vivo de cada aplicación.
  • Se configura con archivos YAML dentro de /app/config: settings.yaml, services.yaml, widgets.yaml, bookmarks.yaml y docker.yaml.
  • Fija siempre una versión concreta como ghcr.io/gethomepage/homepage:v1.13.2 (publicada en junio de 2026); usar la etiqueta :latest te expone a cambios sin aviso.

¿Qué es Homepage y para qué sirve?

Homepage es un panel de servicios (un dashboard) pensado para ser la primera pestaña que abres cada mañana. En una sola pantalla reúnes accesos a todas las aplicaciones que corres en casa o en tu servidor (nube privada, gestor de descargas, monitor, proxy inverso) y, junto a cada acceso, un pequeño widget que muestra su estado y sus métricas en directo. En lugar de recordar puertos e IP, tienes una portada ordenada por grupos.

Su gran seña de identidad es que está totalmente proxeado y es estático: las llamadas a las API de tus servicios las hace el servidor de Homepage, nunca el navegador, así que tus claves nunca salen al cliente. Al estar construido con Next.js y React, se compila en el arranque y sirve HTML ligero; no necesita base de datos ni un proceso pesado detrás. Por eso rinde de maravilla en hardware modesto y arranca en segundos.

Frente a alternativas como Homarr, que se configura arrastrando y soltando desde el navegador, Homepage apuesta por la configuración como código: todo vive en archivos YAML versionables, lo que encaja con quien ya gestiona su infraestructura con Docker Compose. Si prefieres una portada más clásica de accesos directos, Heimdall es otra opción válida; Homepage destaca cuando quieres widgets con datos en vivo y descubrimiento automático de contenedores.

¿Cómo es el docker-compose.yml de Homepage?

Homepage necesita dos montajes: una carpeta para su configuración YAML y, de forma opcional pero muy recomendable, el socket de Docker en solo lectura para leer el estado de tus contenedores. Este es un docker-compose.yml completo y listo para copiar:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:v1.13.2
    container_name: homepage
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      HOMEPAGE_ALLOWED_HOSTS: "127.0.0.1:3000,panel.midominio.es"
      PUID: "1000"
      PGID: "1000"

Arranca la pila y comprueba el estado:

mkdir -p config
docker compose up -d
docker compose ps
docker compose logs -f homepage

Abre http://127.0.0.1:3000 y verás el panel con su configuración de ejemplo. Conviene detenerse en tres detalles. Primero, HOMEPAGE_ALLOWED_HOSTS es obligatorio desde la versión 1.0: es una lista separada por comas de los nombres de host (con puerto si hace falta) desde los que se puede servir el panel, una defensa contra los ataques de cabecera Host. Si te da un error de host no permitido, ese es el sitio donde añadir tu dominio. Segundo, el socket se monta como :ro (solo lectura), lo mínimo para que Homepage lea el estado; aun así, dar acceso al socket implica confianza, y más abajo verás una alternativa más segura. Y tercero, publicar el puerto como 127.0.0.1:3000:3000 lo deja accesible solo desde el propio servidor: para exponerlo al exterior, hazlo detrás de un proxy inverso como Traefik con HTTPS.

¿Cómo se configura Homepage con archivos YAML?

Toda la configuración vive en la carpeta que montaste en /app/config. En el primer arranque, Homepage crea ahí los archivos de ejemplo, que luego editas con tu editor favorito. Los cinco que más usarás son:

Archivo Para qué sirve
settings.yaml Título, tema, colores, disposición de columnas y fondo.
services.yaml Los grupos y las tarjetas de servicio, con su widget.
widgets.yaml Widgets de cabecera: reloj, recursos del sistema, buscador, saludo.
bookmarks.yaml Enlaces estáticos organizados por categorías.
docker.yaml La conexión con Docker para leer estado y descubrir servicios.

Un services.yaml mínimo agrupa tus aplicaciones y les añade un icono y un enlace. Por ejemplo:

- Multimedia:
    - Jellyfin:
        icon: jellyfin.png
        href: http://192.168.1.10:8096
        description: Servidor multimedia
- Gestión:
    - Portainer:
        icon: portainer.png
        href: http://192.168.1.10:9000
        description: Panel de contenedores

Cada cambio en estos archivos se recarga en caliente: guardas el YAML y el panel se actualiza sin reiniciar el contenedor. Si escribes mal la indentación (recuerda: espacios, nunca tabuladores), Homepage lo indicará en sus logs, que puedes seguir con docker compose logs -f homepage.

¿Cómo descubrir servicios por etiquetas de Docker?

Aquí está la parte que hace especial a Homepage. En lugar de listar cada servicio a mano en services.yaml, puedes dejar que descubra los contenedores automáticamente a partir de las etiquetas (labels) que les pongas. Primero declaras la conexión en docker.yaml:

my-docker:
  socket: /var/run/docker.sock

Después, a cada contenedor que quieras ver en el panel le añades etiquetas con la notación por puntos que empieza por homepage:

    labels:
      homepage.group: Multimedia
      homepage.name: Jellyfin
      homepage.icon: jellyfin.png
      homepage.href: http://192.168.1.10:8096
      homepage.description: Servidor multimedia

Al arrancar, Homepage lee esas etiquetas por el socket y coloca cada servicio en su grupo, sin que toques services.yaml. Incluso puedes activar un widget en vivo con etiquetas homepage.widget.*. La ventaja es enorme: el panel y tus servicios viven en el mismo docker-compose.yml, así que añadir una aplicación nueva es solo cuestión de etiquetarla.

Ten presente una advertencia de seguridad: montar el socket de Docker directamente da mucho poder y obliga a que el contenedor corra como root. La opción recomendada para producción es intercalar un docker-socket-proxy, un contenedor que expone solo la parte de la API que Homepage necesita (leer contenedores), por TCP y en solo lectura. Así Homepage nunca toca el socket real.

¿Cómo personalizar el aspecto y el fondo?

El apartado visual se controla desde settings.yaml. Ahí defines el título del panel, el idioma, si arranca en modo claro u oscuro, cuántas columnas tiene cada grupo y, sobre todo, el fondo. Puedes poner un color, un degradado o una imagen, y ajustar su desenfoque y opacidad para que las tarjetas se lean bien encima:

title: Mi homelab
theme: dark
background:
  image: /images/fondo.jpg
  blur: sm
  opacity: 50
layout:
  Multimedia:
    style: row
    columns: 3

Las imágenes de fondo se sirven desde una subcarpeta images dentro de tu carpeta de configuración. Para retoques más finos hay dos válvulas de escape: custom.css para inyectar tus propios estilos y custom.js para comportamiento a medida. Con esto, y los más de cien iconos de servicio que Homepage reconoce por nombre, tendrás una portada a tu gusto en pocos minutos.

Preguntas frecuentes

¿Homepage es lo mismo que la página de inicio de un navegador?

No, y es una confusión habitual por el nombre. Homepage (de gethomepage) es un panel de servicios autoalojado que muestra y monitoriza las aplicaciones de tu servidor; no tiene relación con la página que tu navegador abre al arrancar. Puedes, eso sí, configurar tu navegador para que abra el panel de Homepage como su página de inicio, y mucha gente lo hace precisamente por eso.

¿Necesito montar el socket de Docker para usar Homepage?

No es obligatorio: sin el socket, Homepage funciona igual listando tus servicios a mano en services.yaml. El socket solo hace falta para dos cosas: mostrar el estado y las estadísticas de cada contenedor, y descubrir servicios automáticamente por etiquetas. Si lo montas, hazlo en solo lectura (:ro) y, en producción, a través de un docker-socket-proxy para no exponer el socket real.

¿Homepage o Homarr: cuál elijo?

Depende de cómo prefieras configurar. Homarr se edita desde el navegador arrastrando y soltando, cómodo si no quieres tocar archivos. Homepage sigue la filosofía de configuración como código en YAML, ideal si ya versionas tu infraestructura y quieres descubrimiento automático por etiquetas de Docker. Ambos son ligeros; elige Homepage si te gusta que todo viva en tu docker-compose.yml.

Conclusión

Con un único docker-compose.yml, una carpeta de configuración y el socket de Docker en solo lectura, Homepage te da una portada rápida y estática para todo tu homelab en el puerto 3000. La editas con archivos YAML versionables, descubres tus contenedores automáticamente por etiquetas y la personalizas hasta el fondo desde settings.yaml. Recuerda fijar la versión de la imagen, declarar HOMEPAGE_ALLOWED_HOSTS y, cuando la saques a Internet, protegerla detrás de un proxy inverso. Si prefieres una alternativa editable desde el navegador, compárala con Homarr o con la clásica Heimdall; si quieres configuración como código, Homepage es difícil de superar.

Fuentes: [1] Documentación oficial de Homepage: instalación con Docker[1], [2] Homepage: integración con Docker y etiquetas[2], [3] Repositorio de Homepage en GitHub[3], [4] Docker Docs: proteger el acceso al socket[4].

Visitas: 0

Fuentes

  1. Documentación oficial de Homepage: instalación con Docker
  2. Homepage: integración con Docker y etiquetas
  3. Repositorio de Homepage en GitHub
  4. Docker Docs: proteger el acceso al socket

Ruta: Paneles y notificaciones self-hosted con Docker