Publicado por
Homepage: Dashboard de aplicaciones personalizable con integraciones Docker y API
Una página de inicio moderna, totalmente estática, rápida y segura con integraciones para más de 100 servicios y traducciones a múltiples idiomas. Configurable mediante archivos YAML o descubrimiento automático por etiquetas Docker.
Vídeo tutorial en YouTube
Mira el vídeo completo sobre cómo instalar y usar Homepage: Dashboard de aplicaciones personalizable con integraciones Docker y API en el canal GENBYTE:
¿Qué es Homepage: Dashboard de aplicaciones personalizable con integraciones Docker y API?
Homepage es una aplicación dashboard (o startpage) altamente personalizable diseñada para servir como punto de acceso central a servicios autohospedados. Genera un sitio estático en tiempo de compilación para cargas instantáneas, proxea todas las peticiones API a servicios backend manteniendo las claves ocultas, y ofrece soporte nativo para Docker con descubrimiento automático de contenedores mediante etiquetas. Incluye widgets de información (clima, hora, búsqueda, estado del sistema) y widgets de servicio para aplicaciones populares como *arr, Plex, Jellyfin, Transmission, qBittorrent y muchas más. La configuración se realiza mediante archivos YAML en un directorio montado, permitiendo definir servicios, marcadores, temas, diseño y proveedores de información sin tocar código.
Características principales
Rendimiento estático
El sitio se genera estáticamente en tiempo de compilación (Next.js output: standalone) para tiempos de carga instantáneos sin renderizado del lado del servidor en producción.
Seguridad por proxy
Todas las peticiones API a servicios backend se proxean a través del servidor Homepage, manteniendo claves API y credenciales fuera del navegador del cliente.
Multi-arquitectura
Imágenes Docker disponibles para AMD64 y ARM64, compatibles con Raspberry Pi, servidores x86_64 y entornos heterogéneos.
Internacionalización completa
Soporte para más de 40 idiomas mediante next-i18next, con detección automática y cambio de idioma en la interfaz.
Marcadores de servicios y web
Permite añadir enlaces personalizados a servicios internos y sitios externos, organizados en grupos y con iconos personalizados.
Integración Docker nativa
Estado y estadísticas de contenedores en tiempo real. Descubrimiento automático de servicios mediante etiquetas Docker (labels) para añadir aplicaciones al dashboard sin configuración manual.
Widgets de servicio (100+)
Integraciones listas para Radarr, Sonarr, Lidarr, Bazarr, Ombi, Tautulli, Plex, Jellyfin, Emby, Transmission, qBittorrent, Deluge, Jackett, NZBGet, SABnzbd y decenas más, mostrando estado, colas, estadísticas y acciones rápidas.
Widgets de información y utilidad
Proveedores integrados para clima (OpenWeather, WeatherAPI, etc.), hora, fecha, búsqueda web, Glances (monitor de sistema), estado de Kubernetes, servidores de juego y más.
Personalización profunda
Temas personalizados, CSS/JS personalizado, layouts flexibles, formato de fecha/hora, localización, ordenación, columnas, estilos de tarjetas y configuración global mediante settings.yaml.
Autenticación opcional
Flujo OIDC integrado o login simple por contraseña (opt-in) para añadir una capa de autenticación básica frente a redes no confiables.
Requisitos del sistema
- Docker Engine 20.10+ y Docker Compose v2 (recomendado para despliegue)
- Node.js 22+ y pnpm 9+ (solo para desarrollo o build desde fuente)
- Directorio de configuración local accesible y escribible por UID/GID 1000 (por defecto)
- Acceso al socket Docker (/var/run/docker.sock) en modo solo lectura para descubrimiento automático y widgets de contenedores (opcional)
- Variable de entorno HOMEPAGE_ALLOWED_HOSTS obligatoria con el host/puerto público (ej. gethomepage.dev o mihost:3000)
- Puertos: 3000/TCP expuesto en el contenedor (mapear al puerto deseado en host)
- Arquitectura compatible: linux/amd64 o linux/arm64
Instalación con Docker Compose
Despliegue con Docker Compose (recomendado)
Crea un archivo docker-compose.yml con el siguiente contenido. Ajusta la ruta de configuración local, el host permitido y los UID/GID si difieren de 1000. El socket Docker se monta en solo lectura para permitir descubrimiento automático y widgets de contenedores.
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
environment:
HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # requerido, incluir puerto si no es 80/443
PUID: 1000 # opcional, UID del usuario propietario de la config
PGID: 1000 # opcional, GID del grupo propietario de la config
ports:
– 3000:3000
volumes:
– /path/to/config:/app/config # asegúrate de que el directorio exista
– /var/run/docker.sock:/var/run/docker.sock:ro # opcional, para integraciones Docker
restart: unless-stopped
Despliegue con docker run
Equivalente en una sola línea para entornos sin Compose. Mismos requisitos de volúmenes, variables y puertos.
-e HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev \
-e PUID=1000 \
-e PGID=1000 \
-p 3000:3000 \
-v /path/to/config:/app/config \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
–restart unless-stopped \
ghcr.io/gethomepage/homepage:latest
Instalación desde código fuente (desarrollo)
Clona el repositorio, instala dependencias con pnpm, compila la versión de producción y ejecuta el servidor. Requiere Node.js 22+ y pnpm. La primera vez, copia el esqueleto de configuración.
cd homepage
pnpm install
pnpm build
cp -r src/skeleton config # primera vez only
HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev:3000 pnpm start
Acceder al proyecto
Interfaz web
Accede a http://<host>:<puerto_mapeado> (por defecto http://localhost:3000) tras iniciar el contenedor. La variable HOMEPAGE_ALLOWED_HOSTS debe coincidir con el host y puerto usados para acceder (incluyendo puerto si no es 80/443).
Healthcheck interno
El contenedor expone un endpoint de salud en /api/healthcheck (puerto 3000 interno) usado por el HEALTHCHECK de Docker (intervalo 10s, timeout 3s, inicio 20s).
Casos de uso
- Panel de inicio personal para acceder a todos los servicios autohospedados desde una sola página
- Dashboard de monitorización de contenedores Docker con estado, uso de CPU/RAM/red y logs rápidos
- Centro de control para stack *arr (Radarr, Sonarr, Lidarr, Bazarr, Prowlarr) con colas, estado de salud y búsquedas
- Agregador de medios: Plex, Jellyfin, Emby, Tautulli, Overseerr, Ombi en una vista unificada
- Gestión de descargas: Transmission, qBittorrent, Deluge, SABnzbd, NZBGet con estadísticas y acciones
- Monitor de infraestructura: Glances, Kubernetes, servidores de juego, UPS, sensores de temperatura
- Página de inicio familiar con clima, hora, marcadores web y accesos rápidos a servicios internos
- Portal de servicios para equipos pequeños con autenticación OIDC o contraseña simple
Configuración avanzada
Configuración mediante YAML
Todos los ajustes residen en /app/config (montado desde host). Archivos principales: services.yaml (servicios y widgets), bookmarks.yaml (marcadores), docker.yaml (etiquetas de descubrimiento), settings.yaml (tema, layout, idioma, proveedores, autenticación), widgets.yaml (proveedores de información), kubernetes.yaml (clústeres K8s). La documentación oficial detalla cada clave y ejemplo.
# config/
# services.yaml # definiciones de servicios y widgets
# bookmarks.yaml # enlaces web y de servicios
# docker.yaml # reglas de descubrimiento por labels
# settings.yaml # tema, layout, i18n, auth, etc.
# widgets.yaml # proveedores de info (clima, search, etc.)
# kubernetes.yaml # configuración de clústeres K8s (opcional)
# custom.css # estilos personalizados (opcional)
# custom.js # scripts personalizados (opcional)
Descubrimiento automático de servicios Docker
Añade etiquetas a tus contenedores para que Homepage los detecte y añada automáticamente. Etiquetas clave: homepage.enable=true, homepage.group=Grupo, homepage.name=Nombre, homepage.icon=icono, homepage.widget.type=tipo_widget, homepage.widget.url/key/… según widget. Ver documentación para esquema completo.
– homepage.enable=true
– homepage.group=Media
– homepage.name=Radarr
– homepage.icon=radarr
– homepage.widget.type=radarr
– homepage.widget.url=http://radarr:7878
– homepage.widget.key=API_KEY
Autenticación OIDC o contraseña simple
Configurable en settings.yaml. OIDC requiere proveedor compatible (Authentik, Keycloak, Authelia, etc.). Contraseña simple usa hash bcrypt. Ambas opciones añaden middleware de autenticación a toda la aplicación. Requiere HTTPS y validación de Host headers en proxy inverso.
auth:
method: oidc # o 'password'
oidc:
provider_url: https://auth.example.com
client_id: homepage
client_secret: ${OIDC_CLIENT_SECRET}
# … más opciones
# password:
# username: admin
# password: $2b$10$… # hash bcrypt
Temas y CSS personalizado
Define theme en settings.yaml (built-in: default, dark, solarized, etc.) o crea custom.css en /app/config para sobrescribir estilos. También se puede inyectar custom.js para lógica adicional. Los cambios en CSS/JS se aplican en caliente tras recargar navegador.
theme: default # o ruta a tema personalizado
# custom.css y custom.js en /app/config se cargan automáticamente si existen
Gestión y mantenimiento
Actualización de imagen Docker
Trae la última imagen y recrea el contenedor. Los datos de configuración persisten en el volumen montado. Ejecuta docker compose pull && docker compose up -d (o docker pull + docker run con mismos parámetros).
docker compose up -d
Verificación de salud y logs
El contenedor incluye HEALTHCHECK nativo (wget a /api/healthcheck). Consulta estado con docker ps o docker inspect. Logs disponibles via docker logs homepage (stdout/stderr del proceso Node.js).
# o
docker inspect –format='{{.State.Health.Status}}' homepage
docker logs -f homepage
Backup de configuración
La configuración completa reside en el directorio montado en /app/config. Realiza copias de seguridad de ese directorio (archivos YAML, custom.css, custom.js, iconos personalizados). No hay base de datos externa.
Migración de versión mayor
Revisa el CHANGELOG y la guía de migración en la documentación oficial antes de actualizar entre versiones mayores (ej. v1 -> v2). Pueden cambiar claves de YAML, estructura de widgets o variables de entorno.
Stack técnico
- Next.js 16 (React 19) – Framework React con salida standalone
- Node.js 22 – Runtime JavaScript (builder y runner)
- pnpm – Gestor de paquetes rápido y determinista
- TypeScript 6 – Tipado estático
- Tailwind CSS 4 – Utilidades CSS para UI
- i18next / next-i18next – Internacionalización (40+ idiomas)
- Dockerode – API Docker para descubrimiento y stats de contenedores
- Systeminformation – Métricas de sistema (CPU, RAM, disco, red, sensores)
- Recharts – Gráficos SVG para widgets de estadísticas
- Winston – Logging estructurado
- NextAuth.js – Autenticación OIDC/credenciales
- Docker multi-stage build – Builder (node:22-slim) + Runner (node:22-alpine)
- Healthcheck nativo – wget a /api/healthcheck
- su-exec / shadow – Gestión de UID/GID en entrypoint
- Zensical – Generador de documentación estática (MkDocs-like)
Referencias oficiales
- Repositorio oficial GitHub: https://github.com/gethomepage/homepage
- Documentación oficial: https://gethomepage.dev/
- Guía de instalación: https://gethomepage.dev/installation/
- Configuración de servicios y widgets: https://gethomepage.dev/configs/services/
- Descubrimiento automático Docker: https://gethomepage.dev/configs/docker/#automatic-service-discovery
- Widgets de servicio disponibles: https://gethomepage.dev/widgets/
- Guía de solución de problemas: https://gethomepage.dev/troubleshooting/
- Discord de la comunidad: https://discord.gg/k4ruYNrudu
- Licencia GPL-3.0: https://github.com/gethomepage/homepage/blob/dev/LICENSE
Apoya el canal GENBYTE
¿Te ha sido útil este contenido?
Suscríbete a YouTube
Newsletter GENBYTE
Ko-fi
Contacto: [email protected]