---
title: "Cómo instalar el panel Homer con Docker en Ubuntu 24.04"
description: "Despliega Homer con Docker en Ubuntu 24.04, define tus servicios en config.yml con iconos y estado, y protégelo con Nginx, HTTPS y autenticación básica."
category: "Productividad Self-Hosted"
language: es
source: https://cubepath.com/es/docs/productividad-self-hosted/instalacion-de-homer-dashboard
updated: 2026-09-25
---

# 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:

```bash
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:

```bash
id -u; id -g
```

```output
1000
1000
```

Crea el archivo de Compose con esos valores:

```bash
nano /opt/homer/docker-compose.yml
```

```yaml
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

```bash
sudo docker compose up -d
```

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

```bash
sudo docker compose ps
ls /opt/homer/assets
```

```output
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:

```bash
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:

```bash
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:

```yaml
---
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:

| Clave | Función |
| --- | --- |
| `title`, `subtitle`, `logo` | Cabecera de la página. `logo` es relativo a `assets/`. |
| `columns` | Número de columnas de tarjetas en pantallas anchas. |
| `defaults.colorTheme` | `auto`, `light` o `dark`. `auto` sigue el tema del sistema. |
| `links` | Enlaces fijos en la barra superior. |
| `services` | Grupos de tarjetas; cada grupo tiene un `name`, un `icon` opcional y una lista `items`. |
| `icon` / `logo` | `icon` usa un icono de Font Awesome (`fas fa-...`, `fab fa-...`); `logo` una imagen de `assets/`. |
| `type` | Convierte la tarjeta en una tarjeta inteligente, por ejemplo `Ping` para mostrar si el servicio responde. |

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:

```bash
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
```

```output
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:

```bash
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`:

```bash
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:

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

Crea el bloque de servidor:

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

```nginx
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:

```bash
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:

```bash
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:

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

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

```bash
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/
```

```output
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:

```bash
nano /opt/homer/assets/custom.css
```

```css
.card {
  border-radius: 12px;
}
```

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

```yaml
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.