Homarr es un panel web autoalojado que reúne en una sola página los enlaces a tus servicios y widgets con información en tiempo real: estado de contenedores Docker, descargas, reproducción multimedia, calendario o tiempo. Se configura desde el navegador con una interfaz de arrastrar y soltar, sin editar archivos YAML. En este tutorial desplegarás Homarr con Docker Compose en Ubuntu 24.04, crearás el usuario administrador, activarás la integración con Docker y lo publicarás en tu dominio con Nginx y un certificado de Let's Encrypt.

Requisitos previos

  • Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 1 GB de RAM.
  • Un usuario no root con privilegios sudo.
  • Docker Engine y el plugin Docker Compose instalados desde el repositorio oficial de Docker.
  • Un dominio o subdominio (en esta guía, inicio.tu_dominio) con un registro DNS A que apunte a la IP pública del servidor.
  • UFW activo con SSH permitido.

Paso 1: Crear el directorio del proyecto

Guarda todo lo relacionado con Homarr en un único directorio. Así el archivo de Compose, la clave de cifrado y los datos quedan juntos y son fáciles de respaldar:

mkdir -p ~/homarr/appdata
cd ~/homarr

Homarr cifra en su base de datos las credenciales de las integraciones (claves de API, contraseñas). Para ello necesita una clave de 64 caracteres hexadecimales en la variable SECRET_ENCRYPTION_KEY. Genérala y guárdala en un archivo .env que Docker Compose leerá automáticamente:

echo "SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32)" > .env
chmod 600 .env

Comprueba que el archivo contiene la clave:

cat .env

SECRET_ENCRYPTION_KEY=3f9c1a7e5b...d24e

Paso 2: Escribir el archivo de Docker Compose

Crea el archivo compose.yaml:

nano ~/homarr/compose.yaml

Añade el siguiente contenido:

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    restart: unless-stopped
    ports:
      - "127.0.0.1:7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
      - TZ=Europe/Madrid

Algunos detalles de esta configuración:

  • ghcr.io/homarr-labs/homarr es la imagen actual del proyecto (versión 1.x). La antigua ghcr.io/ajnart/homarr corresponde a la rama 0.x, que ya no recibe desarrollo.
  • El puerto se publica solo en 127.0.0.1. Docker añade sus propias reglas de iptables y se salta UFW, así que publicar 7575:7575 dejaría el panel abierto a Internet sin cifrar. Accederás a él a través de Nginx.
  • El socket de Docker permite a Homarr listar y controlar contenedores. Da acceso completo al daemon de Docker, así que quita esa línea si no vas a usar la integración.
  • ./appdata guarda la base de datos SQLite, la configuración y los iconos subidos.

Paso 3: Arrancar Homarr

Descarga la imagen y arranca el contenedor en segundo plano:

docker compose up -d

Comprueba que el contenedor está en ejecución:

docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"

NAME      STATUS          PORTS
homarr    Up 19 seconds   127.0.0.1:7575->7575/tcp

Verifica que responde en local:

curl -sI http://127.0.0.1:7575 | head -n 1

HTTP/1.1 307 Temporary Redirect

Una respuesta 200 o una redirección 3xx es correcta: una instalación nueva envía a la página de configuración inicial. Si no obtienes respuesta, revisa los registros con docker compose logs homarr.

Paso 4: Publicar Homarr con Nginx y HTTPS

Instala Nginx y Certbot con su plugin para Nginx:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

Crea un bloque de servidor para el subdominio:

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

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

    location / {
        proxy_pass http://127.0.0.1:7575;
        proxy_http_version 1.1;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Las cabeceras Upgrade y Connection permiten las conexiones WebSocket que Homarr usa para actualizar los widgets en tiempo real.

Activa el sitio, comprueba la sintaxis y recarga Nginx:

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

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Abre HTTP y HTTPS en el cortafuegos:

sudo ufw allow 'Nginx Full'

Solicita el certificado. Certbot valida el dominio, añade la configuración TLS al bloque de servidor y crea la redirección de HTTP a HTTPS:

sudo certbot --nginx -d inicio.tu_dominio

Successfully deployed certificate for inicio.tu_dominio to /etc/nginx/sites-enabled/homarr
Congratulations! You have successfully enabled HTTPS on https://inicio.tu_dominio

Certbot instala un temporizador de systemd que renueva el certificado automáticamente. Puedes probar la renovación con sudo certbot renew --dry-run.

Paso 5: Completar la configuración inicial

Abre https://inicio.tu_dominio en el navegador. Homarr muestra un asistente de configuración:

  1. Elige empezar desde cero (también permite importar una configuración de Homarr 0.x).
  2. Crea el usuario administrador con un nombre y una contraseña robusta.
  3. Revisa los ajustes básicos, como el idioma y la analítica anónima, y termina el asistente.

Al acabar se abre el tablero por defecto. El registro público está desactivado: los nuevos usuarios los crea el administrador desde Management > Users (Gestión > Usuarios si has elegido la interfaz en español), donde también puedes crear grupos y limitar qué tableros puede ver o editar cada uno.

Paso 6: Añadir aplicaciones y widgets

En Homarr hay dos conceptos distintos:

  • Aplicaciones: enlaces a tus servicios con nombre, icono y URL. Opcionalmente, Homarr comprueba si responden y muestra un indicador de estado.
  • Integraciones: conexiones con la API de un servicio (Docker, Jellyfin, Sonarr, Radarr, Pi-hole, AdGuard Home, etc.) que alimentan los widgets con datos.

Para añadir una aplicación, entra en Management > Apps y crea una nueva, rellena el nombre y la URL, y elige un icono de la biblioteca integrada. Después, en el tablero, pulsa el botón de edición (el lápiz), añade un elemento de tipo aplicación y coloca la aplicación en la cuadrícula. Guarda los cambios al salir del modo edición.

Para una integración con API, por ejemplo Sonarr:

  1. En Sonarr, copia la clave de API desde Settings > General > Security.
  2. En Homarr, abre Management > Integrations, crea una nueva y elige Sonarr.
  3. Introduce la URL interna (por ejemplo, http://your_server_ip:8989) y la clave de API. Homarr prueba la conexión antes de guardar.
  4. En el tablero, añade el widget de calendario y selecciona la integración.

Paso 7: Activar la integración con Docker

Como el socket de Docker ya está montado, Homarr puede mostrar el estado de los contenedores del servidor. En el tablero, entra en modo edición, añade el widget de contenedores de Docker y guarda. El widget lista los contenedores con su estado y permite arrancarlos, pararlos o reiniciarlos.

Si el widget sale vacío, comprueba que el socket está montado dentro del contenedor:

docker exec homarr ls -l /var/run/docker.sock

srw-rw---- 1 root 988 0 Sep 25 09:12 /var/run/docker.sock

Si el comando devuelve No such file or directory, revisa la línea del volumen en compose.yaml y recrea el contenedor con docker compose up -d.

Paso 8: Actualizar y hacer copias de seguridad

Para actualizar a la última versión, descarga la imagen nueva y recrea el contenedor. Los datos se conservan porque viven en ./appdata:

cd ~/homarr
docker compose pull
docker compose up -d
docker image prune -f

Para una copia de seguridad consistente, detén el contenedor un momento y empaqueta el directorio completo, que incluye la base de datos y el archivo .env con la clave de cifrado:

cd ~
docker compose -f ~/homarr/compose.yaml stop
sudo tar -czf homarr-backup-$(date +%F).tar.gz homarr
docker compose -f ~/homarr/compose.yaml start

Comprueba que el archivo se ha creado:

ls -lh ~/homarr-backup-*.tar.gz

Guarda la copia fuera del servidor, por ejemplo en un almacenamiento de objetos.

Solución de problemas

Error sobre SECRET_ENCRYPTION_KEY en los registros. La variable está vacía o no tiene 64 caracteres hexadecimales. Comprueba que .env está en el mismo directorio que compose.yaml y que ejecutas docker compose desde ahí.

502 Bad Gateway en Nginx. Homarr no escucha en 127.0.0.1:7575. Revisa docker compose ps y docker compose logs homarr; tras una actualización el primer arranque puede tardar unos segundos mientras migra la base de datos.

Los widgets no se actualizan en tiempo real. Falta la configuración de WebSocket en Nginx. Comprueba que el bloque location incluye las cabeceras Upgrade y Connection y recarga Nginx.

Una integración falla al probar la conexión. La URL no es alcanzable desde el contenedor. Pruébala desde dentro con docker exec homarr wget -qO- http://sonarr:8989 o usa la IP del servidor en lugar de localhost.

Conclusión

Tienes Homarr funcionando con Docker Compose, accesible por HTTPS en tu dominio, con un usuario administrador y la integración con Docker activa. A partir de aquí puedes conectar el resto de tus servicios como integraciones, crear tableros distintos por usuario o grupo, y añadir una capa de autenticación única con OIDC si ya usas un proveedor como Authentik o Keycloak.