Instalación y Configuración de Homer Dashboard

Homer es un panel de inicio estático y ligero que centraliza el acceso a todos tus servicios self-hosted en una página web organizada y personalizable. Configurado completamente mediante un archivo YAML, Homer no requiere base de datos y puede desplegarse en segundos con Docker. Esta guía cubre la instalación y configuración completa de Homer en Linux para gestionar tu infraestructura de servicios.

Requisitos Previos

  • Servidor con Ubuntu 20.04+, Debian 11+ o CentOS 8+
  • Docker instalado (método recomendado)
  • O servidor web estático (Nginx, Apache)
  • Puerto 8080 disponible (configurable)
  • Acceso a los URLs de tus servicios self-hosted

Instalación con Docker

# Crear directorio para la configuración de Homer
mkdir -p ~/homer/{assets,assets/icons,assets/tools}

# Descargar el archivo de configuración de ejemplo
wget -O ~/homer/assets/config.yml \
  https://raw.githubusercontent.com/bastienwirtz/homer/main/public/assets/config.yml.dist

# Ejecutar Homer con Docker
docker run -d \
  --name homer \
  --restart unless-stopped \
  -p 8080:8080 \
  -v ~/homer/assets:/www/assets \
  -u $(id -u):$(id -g) \
  b4bz/homer:latest

Acceder al panel en http://TU-SERVIDOR:8080.

Instalación con Docker Compose

mkdir -p ~/homer/assets && cd ~/homer

# Crear docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3'

services:
  homer:
    image: b4bz/homer:latest
    container_name: homer
    restart: unless-stopped
    ports:
      - 8080:8080
    volumes:
      - ./assets:/www/assets
    user: "1000:1000"
    environment:
      - INIT_ASSETS=1  # Copiar assets por defecto si el directorio está vacío
EOF

docker compose up -d

Configuración YAML de Homer

La configuración completa de Homer se realiza en ~/homer/assets/config.yml:

---
# Configuración principal de Homer
title: "Mi Panel de Servicios"
subtitle: "Infraestructura self-hosted"
logo: "logo.png"

# Columnas del panel (1, 2 o 3)
columns: "3"

# Fondo del panel (color CSS o URL de imagen)
background: "#f5f5f5"

# Opciones de conexectividad
connectivityCheck: true

# Configuración del tema
theme: default  # default, material-design
colors:
  light:
    highlight-primary: "#3367d6"
    highlight-secondary: "#4285f4"
    highlight-hover: "#5a95f5"
    background: "#f5f5f5"
    card-background: "#ffffff"
    text: "#363636"
    text-header: "#ffffff"
    text-title: "#303030"
    text-subtitle: "#424242"
    card-shadow: rgba(0, 0, 0, 0.1)
    link: "#3273dc"
    link-hover: "#363636"
  dark:
    highlight-primary: "#3367d6"
    highlight-secondary: "#4285f4"
    highlight-hover: "#5a95f5"
    background: "#131313"
    card-background: "#2b2b2b"
    text: "#eaeaea"
    text-header: "#ffffff"
    text-title: "#fafafa"
    text-subtitle: "#f5f5f5"
    card-shadow: rgba(0, 0, 0, 0.4)
    link: "#3273dc"
    link-hover: "#ffdd57"

# Mensaje informativo en la cabecera
message:
  style: "is-dark"
  title: "Bienvenido"
  content: "Panel de administración de infraestructura self-hosted."

# Atajos de teclado en el buscador integrado
links:
  - name: "Documentación"
    icon: "fas fa-book"
    url: "https://docs.tu-dominio.com"
    target: "_blank"
  - name: "GitHub"
    icon: "fab fa-github"
    url: "https://github.com/tu-usuario"
    target: "_blank"

# Definición de servicios agrupados
services:
  - name: "Monitorización"
    icon: "fas fa-heartbeat"
    items:
      - name: "Grafana"
        logo: "assets/icons/grafana.png"
        subtitle: "Métricas y dashboards"
        tag: "monitor"
        url: "https://grafana.tu-dominio.com"
        target: "_blank"

      - name: "Uptime Kuma"
        logo: "assets/icons/uptime-kuma.png"
        subtitle: "Monitorización de uptime"
        url: "https://status.tu-dominio.com"
        target: "_blank"

  - name: "Almacenamiento"
    icon: "fas fa-database"
    items:
      - name: "Nextcloud"
        logo: "assets/icons/nextcloud.png"
        subtitle: "Almacenamiento en la nube"
        url: "https://cloud.tu-dominio.com"
        target: "_blank"

      - name: "Seafile"
        logo: "assets/icons/seafile.png"
        subtitle: "Sincronización de archivos"
        url: "https://seafile.tu-dominio.com"
        target: "_blank"

Agrupación de Servicios

# Estructura de agrupación en config.yml

services:
  # Grupo de medios
  - name: "Medios"
    icon: "fas fa-film"
    items:
      - name: "Jellyfin"
        logo: "assets/icons/jellyfin.png"
        subtitle: "Servidor de medios"
        tag: "media"
        url: "https://jellyfin.tu-dominio.com"

      - name: "Navidrome"
        logo: "assets/icons/navidrome.png"
        subtitle: "Música"
        url: "https://music.tu-dominio.com"

  # Grupo de productividad
  - name: "Productividad"
    icon: "fas fa-tasks"
    items:
      - name: "Vikunja"
        logo: "assets/icons/vikunja.png"
        subtitle: "Gestión de tareas"
        url: "https://tasks.tu-dominio.com"

      - name: "Paperless"
        logo: "assets/icons/paperless.png"
        subtitle: "Gestión documental"
        url: "https://docs.tu-dominio.com"

  # Grupo de red
  - name: "Red y Seguridad"
    icon: "fas fa-network-wired"
    items:
      - name: "Portainer"
        logo: "assets/icons/portainer.png"
        subtitle: "Gestión Docker"
        url: "https://portainer.tu-dominio.com"

      - name: "Nginx Proxy Manager"
        logo: "assets/icons/nginx.png"
        subtitle: "Proxy inverso"
        url: "https://proxy.tu-dominio.com"

Iconos Personalizados

Homer soporta iconos de múltiples fuentes:

# 1. Iconos de FontAwesome (incluidos por defecto)
# icon: "fas fa-home"  # FontAwesome Solid
# icon: "fab fa-github"  # FontAwesome Brands

# 2. Imágenes personalizadas (PNG, SVG)
# Copiar los iconos al directorio de assets
cp mis-iconos/*.png ~/homer/assets/icons/

# En el config.yml usar:
# logo: "assets/icons/mi-servicio.png"

# 3. Descargar iconos populares de self-hosted desde el repositorio oficial
wget https://raw.githubusercontent.com/walkxcode/dashboard-icons/main/png/jellyfin.png \
  -O ~/homer/assets/icons/jellyfin.png

wget https://raw.githubusercontent.com/walkxcode/dashboard-icons/main/png/grafana.png \
  -O ~/homer/assets/icons/grafana.png

# Script para descargar múltiples iconos
for servicio in jellyfin plex navidrome nextcloud portainer grafana; do
  wget -q "https://raw.githubusercontent.com/walkxcode/dashboard-icons/main/png/${servicio}.png" \
    -O ~/homer/assets/icons/${servicio}.png
  echo "Descargado: ${servicio}.png"
done

Verificación de Estado de Servicios

Homer puede verificar automáticamente si los servicios están activos:

# En el config.yml, agregar tipo de verificación a cada servicio

services:
  - name: "Servicios"
    items:
      # Verificación básica (ping HTTP)
      - name: "Grafana"
        url: "https://grafana.tu-dominio.com"
        type: "Ping"

      # Verificación de estado JSON
      - name: "Jellyfin"
        url: "https://jellyfin.tu-dominio.com"
        type: "Jellyfin"

      # Verificación de Prometheus
      - name: "Prometheus"
        url: "https://prometheus.tu-dominio.com"
        type: "Prometheus"

      # Sin verificación (link simple)
      - name: "Mi Blog"
        url: "https://blog.tu-dominio.com"
        # Sin "type" = enlace simple sin verificación de estado

Homer incluye verificadores integrados para:

  • Ping: Verificación básica HTTP (código 2xx)
  • Jellyfin: Verifica la API de Jellyfin
  • Plex: Verifica el estado de Plex
  • Prometheus: Verifica métricas de Prometheus
  • Portainer: Verifica contenedores Docker

Personalización del Tema

# Tema oscuro por defecto
defaults:
  layout: columns
  colorTheme: dark

# CSS personalizado (agregar archivo en assets/)
customCss: "custom.css"

# Crear CSS personalizado
cat > ~/homer/assets/custom.css << 'EOF'
/* Fuente personalizada */
body {
    font-family: 'Inter', sans-serif;
}

/* Estilo de tarjetas */
.card {
    border-radius: 12px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

/* Fondo con gradiente */
#app {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
EOF

Proxy Inverso con Nginx

# Configuración de Nginx para Homer
sudo tee /etc/nginx/sites-available/homer << 'EOF'
server {
    listen 443 ssl http2;
    server_name inicio.tu-dominio.com;

    ssl_certificate /etc/letsencrypt/live/inicio.tu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/inicio.tu-dominio.com/privkey.pem;

    # Autenticación básica opcional (para proteger el panel)
    # auth_basic "Panel de administración";
    # auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
        # Caché para assets estáticos
        proxy_cache_valid 200 1d;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/homer /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# Proteger Homer con contraseña básica (opcional)
sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd admin

Solución de Problemas

Homer muestra un panel vacío:

# Verificar que el archivo config.yml es YAML válido
docker exec homer cat /www/assets/config.yml

# Validar el YAML
python3 -c "import yaml; yaml.safe_load(open('~/homer/assets/config.yml'))"

# Ver los logs de Homer
docker logs homer

# Verificar permisos del archivo de configuración
ls -la ~/homer/assets/config.yml

Los iconos no aparecen:

# Verificar que los archivos de iconos existen
ls -la ~/homer/assets/icons/

# Comprobar que los permisos son correctos
chmod -R 644 ~/homer/assets/icons/
chmod 755 ~/homer/assets/icons/

# Verificar la ruta en el config.yml (debe ser relativa a /www/assets/)
# logo: "assets/icons/grafana.png"  ← correcto
# logo: "/www/assets/icons/grafana.png"  ← incorrecto

La verificación de estado siempre muestra rojo:

# Homer no soporta autenticación para las verificaciones de estado
# Si el servicio requiere autenticación, Homer no podrá verificarlo

# Verificar que el servicio es accesible desde el servidor de Homer
docker exec homer wget -q -O /dev/null https://grafana.tu-dominio.com && echo "OK" || echo "FALLO"

# Revisar la configuración de CORS si el panel es accesible desde otro dominio

Conclusión

Homer es el punto de partida ideal para cualquier infraestructura self-hosted, proporcionando acceso rápido a todos los servicios desde un único panel web sin sobrecargar el servidor. Su configuración mediante YAML simple y la compatibilidad con iconos de FontAwesome y personalizados lo hacen muy fácil de mantener y adaptar a medida que crece tu infraestructura.