Homepage Docker Compose: Dashboard Moderno para tu Homelab 2025

Si gestionas múltiples servicios self-hosted en tu homelab, sabes lo caótico que puede ser recordar puertos, URLs y accesos. Homepage Docker Compose es la solución definitiva: un dashboard moderno que centraliza todos tus servicios en una interfaz elegante y funcional. En esta guía completa te enseño cómo desplegarlo en minutos y aprovechar sus widgets inteligentes.

¿Qué es Homepage Docker Compose?

Homepage es un dashboard de aplicaciones self-hosted completamente estático, rápido y seguro que te permite organizar y acceder a más de 200 servicios desde una única interfaz. A diferencia de otras soluciones, esta aplicación genera su contenido estáticamente durante el build, lo que garantiza una velocidad de carga excepcional.

Lo que hace especial a esta herramienta es su capacidad de descubrimiento automático de contenedores Docker mediante labels, su sistema de widgets informativos en tiempo real, y su configuración declarativa mediante archivos YAML. Además, todos los API requests se proxean automáticamente, manteniendo tus credenciales ocultas y seguras.

Características principales de Homepage

• Más de 200 integraciones: Conecta con Plex, Jellyfin, Radarr, Sonarr, qBittorrent, Home Assistant, Grafana, Prometheus y muchos más
• Descubrimiento automático: Detecta servicios Docker mediante labels sin configuración manual
• Widgets informativos: Clima, recursos del sistema, información de Kubernetes, búsqueda y más
• Totalmente personalizable: Temas custom, CSS y JavaScript propios
• Multiidioma: Disponible en más de 40 idiomas
• Seguridad first: Proxy completo de API requests para proteger credenciales
• Rendimiento excepcional: Generación estática para carga ultrarrápida

Requisitos previos para Homepage Docker Compose

Antes de comenzar con el despliegue, asegúrate de tener:

• Docker y Docker Compose instalados
• Al menos 512MB de RAM disponible
• Acceso al socket de Docker (/var/run/docker.sock) para descubrimiento automático
• Puerto 3000 disponible (o el que prefieras configurar)

Instalación básica con Homepage Docker Compose

Crear tu dashboard es sorprendentemente simple. Primero, crea un directorio para los archivos de configuración:

mkdir -p ~/homepage/config
cd ~/homepage

Ahora crea el archivo docker-compose.yml con esta configuración optimizada:

version: "3.8"

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Madrid
    networks:
      - homepage_network

networks:
  homepage_network:
    driver: bridge

Inicia el contenedor:

docker-compose up -d

Accede a tu dashboard en http://localhost:3000. Verás la interfaz base lista para personalizar.

Configuración de servicios en Homepage

La configuración se realiza mediante archivos YAML en el directorio config. Crea el archivo config/services.yaml para definir tus servicios:

---
# Servicios de media
- Media:
    - Plex:
        icon: plex.png
        href: http://192.168.1.100:32400
        description: Servidor multimedia
        widget:
          type: plex
          url: http://192.168.1.100:32400
          key: tu_plex_token
    
    - Jellyfin:
        icon: jellyfin.png
        href: http://192.168.1.101:8096
        description: Servidor de vídeo open-source
        widget:
          type: jellyfin
          url: http://192.168.1.101:8096
          key: tu_jellyfin_api_key

# Gestión de descargas
- Descargas:
    - qBittorrent:
        icon: qbittorrent.png
        href: http://192.168.1.102:8080
        description: Cliente torrent
        widget:
          type: qbittorrent
          url: http://192.168.1.102:8080
          username: admin
          password: tu_password
    
    - Radarr:
        icon: radarr.png
        href: http://192.168.1.103:7878
        widget:
          type: radarr
          url: http://192.168.1.103:7878
          key: tu_radarr_api_key

# Monitorización
- Monitorización:
    - Grafana:
        icon: grafana.png
        href: http://192.168.1.104:3001
        widget:
          type: grafana
          url: http://192.168.1.104:3001
          username: admin
          password: tu_password

Descubrimiento automático de contenedores Docker

Una de las funcionalidades más potentes es el descubrimiento automático mediante Docker labels. Añade estas labels a tus contenedores existentes:

version: "3.8"

services:
  portainer:
    image: portainer/portainer-ce:latest
    labels:
      - "homepage.group=Gestión"
      - "homepage.name=Portainer"
      - "homepage.icon=portainer.png"
      - "homepage.href=http://192.168.1.105:9000"
      - "homepage.description=Gestión de contenedores"
      - "homepage.widget.type=portainer"
      - "homepage.widget.url=http://192.168.1.105:9000"
      - "homepage.widget.env=1"
      - "homepage.widget.key=tu_portainer_api_key"

El sistema detectará automáticamente estos contenedores y los añadirá al dashboard sin necesidad de editar archivos YAML manualmente.

Widgets informativos y personalización

Añade widgets informativos creando config/widgets.yaml:

---
- resources:
    cpu: true
    memory: true
    disk: /
    
- datetime:
    text_size: xl
    format:
      timeStyle: short
      dateStyle: short
      
- search:
    provider: google
    target: _blank
    
- openmeteo:
    label: Madrid
    latitude: 40.4168
    longitude: -3.7038
    units: metric
    cache: 5

Estos widgets mostrarán información del sistema, fecha/hora, un buscador integrado y el clima de tu ubicación, todo en tiempo real.

Configuración de bookmarks y enlaces rápidos

Crea config/bookmarks.yaml para añadir enlaces útiles:

---
- Desarrollo:
    - GitHub:
        - icon: github.png
          href: https://github.com
    - GitLab:
        - icon: gitlab.png
          href: https://gitlab.com
          
- Documentación:
    - Docker Docs:
        - icon: docker.png
          href: https://docs.docker.com
    - Kubernetes:
        - icon: kubernetes.png
          href: https://kubernetes.io/docs

Temas y personalización visual con Homepage Docker Compose

Personaliza la apariencia creando config/settings.yaml:

---
title: Mi Homelab
favicon: https://tu-dominio.com/favicon.ico
background: https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe
backgroundOpacity: 0.5
theme: dark
color: slate
headerStyle: clean
hideVersion: true
cardBlur: md
language: es

layout:
  Media:
    style: row
    columns: 3
  Descargas:
    style: row
    columns: 4
  Monitorización:
    style: row
    columns: 2

Puedes elegir entre múltiples temas predefinidos o crear el tuyo con CSS personalizado.

Integración con reverse proxy (Traefik/Caddy)

Para exponer tu dashboard de forma segura con HTTPS, integra Traefik o Caddy. Ejemplo con Caddy:

version: "3.8"

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Madrid
    networks:
      - caddy_network
    labels:
      caddy: dashboard.tu-dominio.com
      caddy.reverse_proxy: "{{upstreams 3000}}"

networks:
  caddy_network:
    external: true

Casos de uso prácticos

El dashboard es ideal para:

• Homelabs personales: Centraliza acceso a Plex, Nextcloud, Vaultwarden, Pi-hole
• Entornos DevOps: Monitoriza GitLab, Jenkins, ArgoCD, Grafana, Prometheus
• Gestión de infraestructura: Acceso rápido a Proxmox, Portainer, Nginx Proxy Manager
• Home automation: Integra Home Assistant, Homebridge y dispositivos IoT

Troubleshooting y errores comunes

Problema: Los widgets no muestran datos

Verifica que las API keys sean correctas y que el proxy de Homepage pueda alcanzar los servicios. Revisa los logs con:

docker logs homepage

Problema: Servicios Docker no se detectan automáticamente

Asegúrate de que el socket de Docker esté correctamente montado y que los contenedores tengan las labels apropiadas. Verifica permisos:

ls -la /var/run/docker.sock

Problema: Error de sintaxis YAML

YAML es muy estricto con la indentación. Usa un validador como yamllint.com para verificar tus archivos de configuración.

Comparativa: Homepage vs Homer vs Heimdall

¿Por qué elegir este dashboard sobre alternativas?

Preguntas frecuentes (FAQ)

¿Homepage funciona sin conexión a internet?

Sí, funciona completamente offline excepto para widgets externos como clima o búsqueda web. Todos los servicios locales y widgets del sistema funcionan sin internet.

¿Puedo usar Homepage con Kubernetes?

Absolutamente. La aplicación incluye widgets específicos para Kubernetes que muestran información de clusters, pods, deployments y servicios en tiempo real.

¿Cómo actualizo Homepage a la última versión?

Ejecuta estos comandos en el directorio de tu docker-compose:

docker-compose pull
docker-compose up -d

¿Es seguro exponer Homepage a internet?

El propio dashboard es seguro, pero te recomiendo protegerlo con autenticación mediante Authelia, Authentik o tu reverse proxy. Nunca expongas credenciales de API directamente.

¿Puedo migrar desde Homer a Homepage?

Sí, aunque tendrás que recrear la configuración manualmente. La estructura YAML es similar, pero los widgets requieren configuración adicional de APIs.

Esta solución moderna transformará completamente la gestión de tu homelab. Con más de 20,000 estrellas en GitHub y una comunidad activa, el proyecto continúa evolucionando con nuevas integraciones cada mes. Si buscas un dashboard funcional, rápido y personalizable, esta es tu mejor opción en 2025.