Homarr reúne todos tus servicios self-hosted en una sola portada que montas a golpe de ratón, sin tocar un archivo de configuración. En esta guía lo levantas con un único docker-compose.yml, entras por el puerto 7575, generas la clave de cifrado obligatoria y aprendes a colocar tarjetas y widgets con su editor de arrastrar y soltar. Al final sabrás cuándo te conviene Homarr y cuándo es mejor un panel por archivos como Homepage. La misma explicación está disponible en inglés.

Puntos clave

  • Homarr es un panel (dashboard) de servicios para el homelab, con más de 40 integraciones y más de 20 000 iconos incluidos, que se configura por completo desde el navegador, sin editar YAML.
  • La versión 1.0 es una reescritura desde cero: el repositorio antiguo ajnart/homarr (más de 7 200 estrellas) está archivado y el desarrollo vive ahora en homarr-labs/homarr. Migrar desde la vieja v0.15 exige rehacer el docker-compose.yml.
  • La interfaz escucha en el puerto 7575 y guarda su estado en una base de datos SQLite embebida, dentro del volumen /appdata; no necesitas un servidor de base de datos aparte.
  • Antes de arrancar es obligatorio definir SECRET_ENCRYPTION_KEY, una cadena hexadecimal de 64 caracteres que genera openssl rand -hex 32; sin ella el contenedor se detiene.
  • Fija siempre una versión concreta como ghcr.io/homarr-labs/homarr:v1.70.0; usar la etiqueta :latest te expone a cambios de comportamiento entre versiones sin avisar.

¿Qué es Homarr y para qué sirve?

Homarr es una aplicación de código abierto que actúa como portada de tu homelab: una única página desde la que abres, vigilas y controlas todos los servicios que corres en Docker. En lugar de recordar puertos e IP, colocas una tarjeta por cada aplicación (Jellyfin, Nextcloud, tu router, Portainer) y las agrupas en categorías. Su gran diferencia frente a otros paneles es que toda la configuración se hace desde el navegador, arrastrando y soltando, sin editar un solo archivo de texto.

La idea que conviene interiorizar es que Homarr es un panel con estado: guarda tu diseño, tus usuarios y las credenciales de las integraciones en una base de datos SQLite propia, no en ficheros YAML. Por eso trae autenticación integrada (usuarios, grupos y proveedores externos como OIDC o LDAP) y cifra los datos sensibles con la clave SECRET_ENCRYPTION_KEY que tú generas. Es un modelo más parecido a una aplicación completa que a un simple lienzo de enlaces.

Conviene saber que la versión actual es un proyecto nuevo. La 1.0 fue una reescritura completa que abandonó el código original de la etapa ajnart/homarr (hoy archivado) y renació bajo la organización homarr-labs. Si vienes de la vieja versión 0.15, no basta con actualizar la imagen: cambian la configuración y el almacenamiento, así que tómalo como una instalación desde cero. Como panel de gestión visual encaja bien junto a Portainer, que se ocupa del ciclo de vida de los contenedores mientras Homarr te da la portada.

¿Cómo es el docker-compose.yml de Homarr?

Homarr necesita dos cosas para desplegarse: un volumen persistente donde vivan su base de datos y su configuración, y la clave de cifrado obligatoria. Si además quieres que muestre el estado de tus contenedores, monta el socket de Docker en solo lectura. Primero genera la clave:

openssl rand -hex 32

Copia esa cadena de 64 caracteres. Este es un docker-compose.yml completo, con la versión fijada, el volumen con nombre, el puerto publicado solo en la propia máquina y el socket montado como solo lectura:

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:v1.70.0
    container_name: homarr
    restart: unless-stopped
    volumes:
      - homarr_appdata:/appdata
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:7575:7575"
    environment:
      SECRET_ENCRYPTION_KEY: "pega_aqui_tu_clave_de_64_caracteres"
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:7575"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  homarr_appdata:

Merece la pena detenerse en algunos detalles. El volumen con nombre homarr_appdata se monta en /appdata, la ruta donde Homarr crea la base de datos SQLite (/appdata/db/db.sqlite) y guarda tu diseño; sin ese volumen perderías toda la configuración al recrear el contenedor, que es la razón por la que un panel con estado necesita siempre almacenamiento persistente. La imagen de Homarr no trae su propia comprobación de estado, así que la del ejemplo es una prueba de vida básica: comprueba que el puerto 7575 responde. Y al publicarlo como 127.0.0.1:7575:7575 lo dejas accesible solo desde el propio servidor, porque cualquier panel de gestión debería quedar detrás de un proxy o una VPN, nunca asomado directamente a Internet.

Arranca la pila y comprueba el estado:

docker compose up -d
docker compose ps
docker compose logs -f homarr

Abre http://127.0.0.1:7575 en el navegador. La primera vez, Homarr te pedirá crear la cuenta de administrador; a partir de ahí entrarás siempre con ese usuario.

¿Cómo funciona el editor por arrastrar y soltar?

Aquí está el rasgo que define a Homarr. Desde el propio panel activas el modo edición y la interfaz se convierte en un lienzo: pulsas para añadir un elemento, lo arrastras hasta su sitio y estiras sus bordes para darle el tamaño que quieras. Cada cambio se guarda en la base de datos al instante, sin recargar ni editar archivos.

Los elementos que colocas se dividen en tres tipos:

  • Aplicaciones (apps): tarjetas con el enlace a un servicio, su icono y, opcionalmente, un indicador de estado que comprueba si responde.
  • Widgets: bloques dinámicos como el reloj, el tiempo, un calendario, notas o el estado del sistema.
  • Categorías y separadores: para agrupar y ordenar todo en secciones plegables.

Homarr admite varios tableros (boards) distintos, cada uno con sus permisos, así que puedes tener uno público con enlaces y otro privado con las herramientas de administración. Como los iconos son un dolor de cabeza recurrente en estos paneles, Homarr incluye una biblioteca de más de 20 000 iconos y detecta automáticamente el más adecuado por el nombre de la aplicación. Frente a un panel como Dashy, donde el diseño también se toca por interfaz pero se respalda en un fichero conf.yml, en Homarr no existe ese archivo: la fuente de la verdad es su base de datos.

¿Qué integraciones y widgets ofrece?

Más allá de los enlaces, la gracia de Homarr son las integraciones: conexiones autenticadas con otros servicios que convierten una tarjeta en un panel vivo. Cuando enlazas Homarr con la API de una aplicación, esta empieza a mostrar datos reales en tiempo real dentro del propio dashboard.

Entre las más de cuarenta integraciones disponibles hay categorías muy útiles para un homelab:

  • Contenedores: al montar el socket de Docker, Homarr lista tus contenedores, muestra su estado y CPU/RAM, y te permite arrancarlos, pararlos o reiniciarlos desde la propia tabla.
  • Descargas y multimedia: clientes como qBittorrent o Transmission, y gestores como Sonarr, Radarr o Jellyfin, con progreso y colas en directo.
  • Redes y sistema: Pi-hole o AdGuard Home con sus estadísticas, y widgets de estado del propio servidor.

Aquí es donde cobra sentido la clave de cifrado: los tokens y contraseñas de esas integraciones se guardan cifrados en la base de datos con SECRET_ENCRYPTION_KEY. Por eso, si pierdes esa clave, Homarr no podrá descifrar ninguna credencial y todas las integraciones dejarán de funcionar; guárdala tan a buen recaudo como una contraseña. Para publicar el panel de forma segura con HTTPS y un dominio propio, ponlo detrás de un proxy inverso como Traefik.

¿Homarr o Homepage: cuál elegir?

Son las dos formas opuestas de montar un panel, y la elección depende de cómo te guste trabajar. Homarr es una aplicación completa, con base de datos y autenticación, que se configura por interfaz; Homepage es un panel sin estado que se define escribiendo archivos YAML y no guarda nada entre reinicios más allá de esos ficheros.

Criterio Homarr Homepage
Configuración Arrastrar y soltar en el navegador Archivos YAML editados a mano
Almacenamiento Base de datos SQLite Solo ficheros de configuración
Autenticación Integrada (usuarios, OIDC, LDAP) No trae; se delega en un proxy
Multiusuario y tableros Sí, con permisos No de forma nativa
Consumo de recursos Mayor (app con base de datos) Muy ligero

En la práctica, elige Homarr si quieres tocarlo todo con el ratón, compartirlo con varias personas y no pelearte con la sintaxis YAML. Elige Homepage si prefieres versionar tu configuración en Git, buscas la menor huella posible y no te importa editar texto. Ninguno es mejor en abstracto: son filosofías distintas para el mismo trabajo.

Preguntas frecuentes

¿Necesita Homarr una base de datos externa?

No. A diferencia de otros paneles con estado, Homarr v1 incluye una base de datos SQLite embebida que vive dentro del volumen /appdata, en /appdata/db/db.sqlite. Con montar ese volumen persistente basta para conservar tu diseño, tus usuarios y las integraciones entre reinicios. Solo si tienes una instalación grande y quieres separar la base de datos puedes apuntar Homarr a un MySQL o PostgreSQL externo mediante variables de entorno, pero no es lo habitual en un homelab.

¿Qué pasa si pierdo la clave SECRET_ENCRYPTION_KEY?

Perderla rompe todas las integraciones. Homarr usa esa clave para cifrar en la base de datos los tokens y contraseñas de los servicios conectados; sin ella no puede descifrarlos, así que dejarían de funcionar y tendrías que volver a introducir cada credencial. La clave no está guardada dentro del contenedor: la defines tú en el docker-compose.yml, de modo que consérvala en tu gestor de contraseñas junto con las copias de seguridad del volumen /appdata.

¿Es obligatorio montar el socket de Docker?

No para el panel básico. Homarr funciona perfectamente como portada de enlaces y widgets sin acceso al socket. Solo lo necesitas si quieres la integración de contenedores, que muestra el estado de tu Docker y te deja gestionarlos desde el navegador. Como montar /var/run/docker.sock concede mucho poder, hazlo en solo lectura (:ro) o, mejor aún, a través de un proxy del socket que limite las operaciones permitidas.

Conclusión

Con un único docker-compose.yml, un volumen persistente y una clave de cifrado de 64 caracteres, Homarr te da una portada del homelab que montas arrastrando tarjetas en el puerto 7575, con más de cuarenta integraciones que muestran datos en vivo. Recuerda fijar la versión de la imagen, guardar la SECRET_ENCRYPTION_KEY a buen recaudo y publicarlo siempre detrás de un proxy inverso, nunca directamente en Internet. Si prefieres versionar la configuración en texto plano, mira Homepage; si quieres tocarlo todo con el ratón, Homarr es tu panel.

Fuentes: [1] Documentación oficial de Homarr[1], [2] Variables de entorno de Homarr[2], [3] Repositorio de Homarr en GitHub[3], [4] Docker Docs: uso de docker compose[4].

Visitas: 0

Fuentes

  1. Documentación oficial de Homarr
  2. Variables de entorno de Homarr
  3. Repositorio de Homarr en GitHub
  4. Docker Docs: uso de docker compose

Ruta: Paneles y notificaciones self-hosted con Docker