Cómo instalar el panel Homer con Docker en Ubuntu 24.04

Homer es un panel de inicio estático que reúne en una sola página los enlaces a todos tus servicios autoalojados, agrupados y con iconos. No necesita base de datos ni backend: toda la configuración vive en un archivo YAML que el navegador lee al cargar la página. En esta guía desplegarás Homer con Docker Compose en Ubuntu 24.04, configurarás tus servicios y lo publicarás con Nginx, HTTPS y autenticación básica.

Requisitos previos

• Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath. Homer consume muy pocos recursos.
• Un usuario no root con privilegios sudo.
• Docker Engine y el plugin Docker Compose instalados desde el repositorio oficial de Docker.
• Un subdominio, por ejemplo inicio.tu_dominio.com, con un registro DNS A apuntando a la IP pública del servidor.
• Los puertos 80 y 443 accesibles desde Internet.

Sustituye inicio.tu_dominio.com por tu subdominio real.

Paso 1: Crear el archivo de Docker Compose

Homer lee su configuración y sus recursos (iconos, logotipo, CSS) del directorio /www/assets del contenedor, que montarás desde el host. Crea el directorio del despliegue:

sudo mkdir -p /opt/homer/assets
sudo chown -R "$USER":"$USER" /opt/homer
cd /opt/homer

El contenedor se ejecuta con el UID y GID que le indiques, y necesita poder escribir en assets la primera vez para copiar los archivos de ejemplo. Consulta los tuyos:

id -u; id -g

1000
1000

Crea el archivo de Compose con esos valores:

nano /opt/homer/docker-compose.yml

services:
  homer:
    image: b4bz/homer:latest
    container_name: homer
    restart: unless-stopped
    user: "1000:1000"
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      INIT_ASSETS: "1"
    volumes:
      - ./assets:/www/assets

Con INIT_ASSETS=1, si el directorio assets está vacío, el contenedor copia en él un config.yml de ejemplo y los iconos por defecto. El puerto se publica solo en 127.0.0.1 porque el acceso público pasará por Nginx.

Paso 2: Arrancar Homer

sudo docker compose up -d

Comprueba que el contenedor está en marcha y que ha creado los archivos iniciales:

sudo docker compose ps
ls /opt/homer/assets

NAME    IMAGE               STATUS
homer   b4bz/homer:latest   Up 10 seconds

config.yml  icons  manifest.json  ...

Verifica que sirve la página y el archivo de configuración:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/
curl -s http://127.0.0.1:8080/assets/config.yml | head -5

El primer comando debe devolver 200 y el segundo mostrar las primeras líneas del config.yml de ejemplo.

Paso 3: Definir tus servicios en config.yml

Sustituye la configuración de ejemplo por la tuya. Guarda antes una copia del original como referencia de todas las opciones:

cp /opt/homer/assets/config.yml /opt/homer/assets/config.yml.example
nano /opt/homer/assets/config.yml

Este es un ejemplo completo con dos grupos de servicios. Adapta los nombres y las URL a los tuyos:

---
title: "Mis servicios"
subtitle: "Servidor principal"
logo: "logo.png"

header: true
columns: "3"
connectivityCheck: true

defaults:
  layout: columns
  colorTheme: auto

links:
  - name: "Documentación"
    icon: "fas fa-book"
    url: "https://docs.tu_dominio.com"
    target: "_blank"

services:
  - name: "Productividad"
    icon: "fas fa-briefcase"
    items:
      - name: "Nextcloud"
        logo: "assets/icons/nextcloud.png"
        subtitle: "Archivos y calendario"
        tag: "archivos"
        url: "https://cloud.tu_dominio.com"
        target: "_blank"
      - name: "Vikunja"
        icon: "fas fa-tasks"
        subtitle: "Gestión de tareas"
        url: "https://tareas.tu_dominio.com"
        target: "_blank"

  - name: "Monitorización"
    icon: "fas fa-heartbeat"
    items:
      - name: "Grafana"
        logo: "assets/icons/grafana.png"
        subtitle: "Métricas"
        url: "https://grafana.tu_dominio.com"
        target: "_blank"
        type: "Ping"

Las claves principales son:

Homer lee config.yml cada vez que se carga la página, así que no hace falta reiniciar el contenedor: basta con recargar el navegador. Antes, comprueba que el YAML es válido, ya que un error de sintaxis deja el panel en blanco:

sudo apt install -y python3-yaml
python3 -c 'import sys, yaml; yaml.safe_load(open(sys.argv[1])); print("YAML válido")' /opt/homer/assets/config.yml

YAML válido

Paso 4: Añadir iconos de tus servicios

Los logotipos referenciados con logo: deben existir en assets. El proyecto de código abierto dashboard-icons mantiene iconos de cientos de aplicaciones autoalojadas. Descarga los que uses en tu configuración:

cd /opt/homer/assets/icons
for app in nextcloud grafana; do
  curl -fsSLo "${app}.png" "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/${app}.png"
done
ls -l nextcloud.png grafana.png

Si algún nombre no existe en el repositorio, curl falla con un error 404 y no crea el archivo; busca el nombre correcto en el repositorio homarr-labs/dashboard-icons de GitHub. Recarga el panel para ver los iconos.

Paso 5: Publicar Homer con Nginx, HTTPS y autenticación básica

El panel revela qué servicios tienes y dónde están, así que conviene protegerlo con contraseña aunque cada servicio tenga su propio inicio de sesión. Instala Nginx, Certbot y la utilidad htpasswd:

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx apache2-utils

Crea el archivo de usuarios. El comando pedirá la contraseña dos veces:

sudo htpasswd -c /etc/nginx/.htpasswd-homer tu_usuario

Crea el bloque de servidor:

sudo nano /etc/nginx/sites-available/homer

server {
    listen 80;
    listen [::]:80;
    server_name inicio.tu_dominio.com;

    auth_basic "Panel de servicios";
    auth_basic_user_file /etc/nginx/.htpasswd-homer;

    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-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Activa el sitio y recarga Nginx:

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

Si usas UFW, permite SSH y el tráfico web:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Obtén el certificado TLS. Certbot añade HTTPS al bloque existente y conserva la autenticación:

sudo certbot --nginx -d inicio.tu_dominio.com

Comprueba que sin credenciales el acceso se deniega y que con ellas funciona:

curl -s -o /dev/null -w '%{http_code}\n' https://inicio.tu_dominio.com/
curl -s -o /dev/null -w '%{http_code}\n' -u tu_usuario https://inicio.tu_dominio.com/

401
Enter host password for user 'tu_usuario':
200

Paso 6: Personalizar el aspecto (opcional)

Para cambios de estilo que no cubren las opciones de config.yml, Homer permite cargar hojas de estilo propias con la clave stylesheet. Crea el archivo:

nano /opt/homer/assets/custom.css

.card {
  border-radius: 12px;
}

Y referéncialo en config.yml, al nivel de title:

stylesheet:
  - "assets/custom.css"

Recarga el navegador para aplicarlo. Los colores de los temas claro y oscuro también se pueden ajustar con el bloque colors que encontrarás en config.yml.example.

Solución de problemas

El panel aparece en blanco o sin servicios. Casi siempre es un error de sintaxis en config.yml (indentación, tabuladores o comillas sin cerrar). Valídalo con el comando del Paso 3 y abre la consola del navegador para ver el error concreto.

El contenedor no arranca o no crea los archivos de ejemplo. El UID de user: no puede escribir en /opt/homer/assets. Revisa los permisos con ls -ln /opt/homer y los logs con sudo docker compose logs homer.

Las tarjetas Ping aparecen siempre en rojo. La comprobación la hace tu navegador, no el servidor. Si el servicio no permite peticiones desde otro origen (CORS), redirige o exige autenticación, la comprobación falla aunque el servicio funcione. Quita type: "Ping" de esas tarjetas o apunta la comprobación a una URL pública del servicio que devuelva 200.

Conclusión

Tienes Homer sirviendo un panel con tus servicios agrupados, con iconos y comprobación de estado, publicado con HTTPS y protegido con contraseña. Como siguientes pasos, guarda /opt/homer/assets en un repositorio Git para versionar la configuración, explora en config.yml.example otras tarjetas inteligentes y añade al panel cada servicio nuevo que despliegues.