Instalación de Homarr: Dashboard Interactivo de Servidor
Homarr es un panel de gestión de servidor moderno y visualmente atractivo que integra widgets en tiempo real con tus aplicaciones Docker, métricas del sistema, reproductores multimedia y mucho más. A diferencia de dashboards estáticos como Homer, Homarr se comunica directamente con servicios como Sonarr, Radarr, Jellyfin y el daemon de Docker para mostrar información dinámica. Esta guía cubre la instalación y configuración completa de Homarr en Linux.
Requisitos Previos
- Servidor con Ubuntu 20.04+, Debian 11+ o CentOS 8+
- Docker instalado y en funcionamiento
- Mínimo 512 MB de RAM
- Puerto 7575 disponible
- Socket de Docker accesible (para integración con contenedores)
Instalación con Docker
# Crear directorio para datos persistentes de Homarr
mkdir -p ~/homarr/{configs,icons,data}
# Ejecutar Homarr con Docker
docker run -d \
--name homarr \
--restart unless-stopped \
-p 7575:7575 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/homarr/configs:/app/data/configs \
-v ~/homarr/icons:/app/public/icons \
-v ~/homarr/data:/data \
ghcr.io/ajnart/homarr:latest
Acceder al panel en http://TU-SERVIDOR:7575.
Instalación con Docker Compose
mkdir -p ~/homarr && cd ~/homarr
cat > docker-compose.yml << 'EOF'
version: '3'
services:
homarr:
image: ghcr.io/ajnart/homarr:latest
container_name: homarr
restart: unless-stopped
ports:
- 7575:7575
volumes:
# Socket de Docker para integración con contenedores
- /var/run/docker.sock:/var/run/docker.sock
# Datos persistentes
- ./configs:/app/data/configs
- ./icons:/app/public/icons
- ./data:/data
environment:
- TZ=Europe/Madrid
# Habilitar autenticación
- AUTH_PROVIDER=credentials
# Contraseña de administrador (solo para el primer inicio)
# - DEFAULT_COLOR_SCHEME=dark
EOF
docker compose up -d
# Ver los logs de inicio
docker compose logs -f homarr
Configuración de la Interfaz
Acceder a http://TU-SERVIDOR:7575 para comenzar la configuración:
Primer inicio:
- Crear cuenta de administrador
- Seleccionar idioma y zona horaria
- Comenzar a agregar servicios y widgets
Interfaz drag-and-drop:
- Clic en "Editar" para entrar en modo edición
- Arrastrar y soltar servicios y widgets al panel
- Redimensionar elementos arrastrando las esquinas
- Organizar en múltiples tableros (Boards)
Agregar un servicio:
- Modo edición > Agregar servicio
- Introducir nombre, URL y seleccionar el tipo de app
- Configurar credenciales de API si es necesario (para datos en tiempo real)
- Seleccionar icono desde la biblioteca integrada
Integración con Docker
Homarr puede leer el estado de los contenedores Docker directamente:
# El socket de Docker debe estar montado en el contenedor de Homarr
# (ya configurado en el docker-compose.yml anterior)
# Verificar que Homarr puede leer los contenedores
docker exec homarr ls /var/run/docker.sock
# Para entornos donde Docker está en otro host, usar Docker TCP:
# Agregar en el docker-compose.yml:
environment:
- DOCKER_HOST=tcp://IP-DOCKER-HOST:2375
Desde el panel web, en cada servicio agregar la integración Docker:
- Tipo de app: Seleccionar la aplicación (Jellyfin, Sonarr, etc.)
- Container name: nombre del contenedor Docker
- Homarr mostrará el estado (ejecutando/detenido) automáticamente
Widgets Disponibles
Homarr incluye una amplia colección de widgets:
Widgets del sistema:
- CPU: Uso de CPU en tiempo real
- RAM: Uso de memoria
- Disco: Espacio en disco
- Red: Tráfico de red en tiempo real
# Para widgets del sistema, habilitar la API de métricas del servidor
# (disponible en versiones recientes de Homarr)
# En el docker-compose.yml agregar:
environment:
- DOCKER_HOST=unix:///var/run/docker.sock
# Y montar /proc para métricas del host (con precaución)
volumes:
- /proc:/host/proc:ro
Widgets multimedia:
- Jellyfin/Plex: Qué se está reproduciendo ahora
- Sonarr: Próximos episodios y estado de descargas
- Radarr: Películas buscadas y descargas en curso
Widgets de información:
- Calendario: Calendario mensual
- Reloj: Hora actual (múltiples zonas horarias)
- Tiempo: Pronóstico meteorológico (requiere API key)
- Búsqueda: Búsqueda web integrada (Google, DuckDuckGo, etc.)
- RSS: Últimas noticias de un feed RSS
- Bookmarks: Marcadores organizados
Ejemplo de configuración del widget de Jellyfin (desde la interfaz):
- Agregar widget > Multimedia > Jellyfin
- URL de Jellyfin:
http://jellyfin:8096 - API Key de Jellyfin: generar en Jellyfin > Panel > API Keys
- Seleccionar qué usuarios monitorizar
Monitorización de Servicios
# Homarr puede verificar el estado HTTP de cualquier servicio
# Configuración por servicio en el modo edición:
# - URL de verificación de estado
# - Intervalo de comprobación
# - Código HTTP esperado (200, etc.)
Para integración con Sonarr/Radarr:
# Obtener la API key de Sonarr
# Sonarr > Configuración > General > Seguridad > Clave API
# Configurar en Homarr:
# Agregar servicio > Sonarr
# URL: http://sonarr:8989
# API Key: TU_API_KEY_SONARR
# Lo mismo para Radarr:
# URL: http://radarr:7878
# API Key: TU_API_KEY_RADARR
Gestión de Usuarios
Homarr soporta múltiples usuarios con permisos diferenciados:
# Tipos de usuarios en Homarr:
# - Admin: Acceso completo, puede editar el panel
# - Usuario: Solo lectura del panel
# - Invitado: Sin autenticación (si se permite)
# Configurar en el panel:
# Configuración (engranaje) > Usuarios > Gestionar usuarios
# Variables de entorno para configuración de autenticación
environment:
- AUTH_PROVIDER=credentials # Autenticación con usuario/contraseña
- NEXTAUTH_URL=https://inicio.tu-dominio.com
- NEXTAUTH_SECRET=$(openssl rand -hex 32)
Para autenticación con OIDC/OAuth (Authelia, Keycloak, etc.):
environment:
- AUTH_PROVIDER=oidc
- OIDC_URI=https://auth.tu-dominio.com
- OIDC_CLIENT_ID=homarr
- OIDC_CLIENT_SECRET=tu-client-secret
- OIDC_ADMIN_GROUP=admins # Grupo OIDC para administradores
Proxy Inverso con Nginx
# Obtener certificado SSL
sudo certbot --nginx -d inicio.tu-dominio.com
# Configuración de Nginx para Homarr
sudo tee /etc/nginx/sites-available/homarr << 'EOF'
server {
listen 443 ssl http2;
server_name inicio.tu-dominio.com;
ssl_certificate /etc/letsencrypt/live/inicio.tu-dominio.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/inicio.tu-dominio.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:7575;
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 https;
# WebSocket para actualizaciones en tiempo real
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
EOF
sudo ln -s /etc/nginx/sites-available/homarr /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
# Actualizar la URL en docker-compose.yml
# NEXTAUTH_URL=https://inicio.tu-dominio.com
docker compose down && docker compose up -d
Solución de Problemas
Homarr no inicia:
# Ver logs del contenedor
docker logs homarr --tail 50
# Verificar permisos de los directorios de datos
ls -la ~/homarr/
sudo chown -R 1000:1000 ~/homarr/
# Verificar acceso al socket de Docker
docker exec homarr ls -la /var/run/docker.sock
Los widgets de Docker no muestran contenedores:
# Verificar que el socket de Docker está montado
docker inspect homarr | grep -A 5 "Binds"
# Comprobar que el usuario del contenedor tiene permisos sobre el socket
# El grupo del socket en el host:
ls -la /var/run/docker.sock
# Agregar el usuario al grupo docker si es necesario
sudo usermod -aG docker usuario
Los iconos de servicios no aparecen:
# Homarr descarga iconos automáticamente desde internet
# Si el servidor no tiene acceso a internet, subir iconos manualmente
ls ~/homarr/icons/
# Descargar iconos del paquete walkxcode/dashboard-icons
wget https://github.com/walkxcode/dashboard-icons/archive/refs/heads/main.zip
unzip main.zip
cp dashboard-icons-main/png/*.png ~/homarr/icons/
Error de autenticación NEXTAUTH:
# NEXTAUTH_URL debe coincidir exactamente con la URL de acceso
# Si usas https, la variable debe tener https://
environment:
- NEXTAUTH_URL=https://inicio.tu-dominio.com # Sin barra final
- NEXTAUTH_SECRET=CLAVE-SECRETA-ALEATORIA
# Regenerar la clave secreta si hay problemas de sesión
openssl rand -hex 32
# Actualizar en docker-compose.yml y reiniciar
Conclusión
Homarr eleva el concepto de panel de servicios a un nivel superior con sus widgets dinámicos e integración directa con aplicaciones multimedia y de automatización. Su interfaz drag-and-drop intuitiva y el soporte para múltiples usuarios lo convierten en la opción ideal para servidores con múltiples servicios self-hosted que necesitan visibilidad en tiempo real del estado de toda la infraestructura.