--- title: "Cómo instalar Homarr con Docker en Ubuntu 24.04" description: "Despliega el panel Homarr con Docker Compose en Ubuntu 24.04, crea el usuario administrador, conecta Docker y publícalo con Nginx y HTTPS de Let's Encrypt." category: "Productividad Self-Hosted" language: es source: https://cubepath.com/es/docs/productividad-self-hosted/instalacion-de-homarr-dashboard-de-servidor updated: 2026-09-25 --- # Cómo instalar Homarr con Docker en Ubuntu 24.04 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: ```bash 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: ```bash echo "SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32)" > .env chmod 600 .env ``` Comprueba que el archivo contiene la clave: ```bash cat .env ``` ```output SECRET_ENCRYPTION_KEY=3f9c1a7e5b...d24e ``` > Importante: guarda esta clave junto a tus copias de seguridad. Si la pierdes, Homarr no podrá descifrar las credenciales de las integraciones que hayas configurado. ## Paso 2: Escribir el archivo de Docker Compose Crea el archivo `compose.yaml`: ```bash nano ~/homarr/compose.yaml ``` Añade el siguiente contenido: ```yaml 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: ```bash docker compose up -d ``` Comprueba que el contenedor está en ejecución: ```bash docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}" ``` ```output NAME STATUS PORTS homarr Up 19 seconds 127.0.0.1:7575->7575/tcp ``` Verifica que responde en local: ```bash curl -sI http://127.0.0.1:7575 | head -n 1 ``` ```output 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: ```bash sudo apt update sudo apt install nginx certbot python3-certbot-nginx ``` Crea un bloque de servidor para el subdominio: ```bash sudo nano /etc/nginx/sites-available/homarr ``` ```nginx 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: ```bash sudo ln -s /etc/nginx/sites-available/homarr /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx ``` ```output 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: ```bash 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: ```bash sudo certbot --nginx -d inicio.tu_dominio ``` ```output 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. > Nota: si Homarr y el otro servicio están en la misma red de Docker, usa el nombre del contenedor en la URL (`http://sonarr:8989`). `localhost` dentro del contenedor de Homarr se refiere al propio contenedor, no al servidor. ## 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: ```bash docker exec homarr ls -l /var/run/docker.sock ``` ```output 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`: ```bash 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: ```bash 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: ```bash 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.