Open Source • Self-hosted • Vue.js

Homer: Página de inicio estática para servidores autogestionados

Dashboard ligero y configurable mediante YAML para organizar servicios y enlaces en tu homelab

Vídeo tutorial en YouTube

Mira el vídeo completo sobre cómo instalar y usar Homer: Página de inicio estática para servidores autogestionados en el canal GENBYTE:

Clickea la miniatura para ir a YouTube

¿Qué es Homer: Página de inicio estática para servidores autogestionados?

Homer es una página de inicio estática (static homepage) diseñada para servidores autogestionados. Permite mantener accesibles todos tus servicios, aplicaciones y enlaces desde una única interfaz web, configurada mediante un sencillo archivo YAML. El proyecto está desarrollado en Vue 3, se sirve como archivos estáticos y no requiere base de datos ni backend dinámico. Es ideal para homelabs, servidores caseros y entornos donde se busca una portada rápida, ligera y sin mantenimiento.

Configuración declarativa en YAML, despliegue inmediato con Docker y compatibilidad PWA para instalarla como aplicación nativa.

Características principales

Configuración YAML simple

Todos los servicios, grupos, enlaces y ajustes visuales se definen en un único archivo assets/config.yml, sin necesidad de base de datos ni panel de administración.

Ligero y rápido

Compilación estática con Vite, servida mediante lighttpd en el contenedor Docker. Tiempo de carga mínimo y consumo de recursos reducido.

Búsqueda difusa (fuzzy search)

Permite localizar servicios al instante escribiendo parte del nombre. Atajo de teclado '/' para abrir la búsqueda.

Tarjetas inteligentes (smart cards)

Soporte para tarjetas que muestran estado, métricas o información dinámica de servicios compatibles (ej. Docker, Pi-hole, Home Assistant, etc.).

Múltiples páginas y agrupación

Organiza los elementos en varias páginas y grupos jerárquicos para mantener la interfaz limpia aunque crezca el número de servicios.

Personalización de temas

Variables CSS, colores, fondos, tipografía y modo oscuro/claro configurables desde el propio YAML o mediante archivos de tema adicionales.

Instalable como PWA

Genera manifest y service worker automáticamente; se puede instalar en el escritorio o dispositivo móvil como una aplicación nativa.

Atajos de teclado

/ para buscar, Escape para cerrar, Enter para abrir el primer resultado, Alt+Enter para abrir en nueva pestaña.

Despliegue flexible

Disponible como imagen Docker oficial (b4bz/homer), tarball precompilado (homer.zip) o compilación manual con pnpm y Vite.

Requisitos del sistema

Docker Engine y Docker Compose (recomendado para producción)
Directorio local para montar la configuración (assets/config.yml y recursos)
Permisos de escritura en el directorio de configuración si se usa INIT_ASSETS=1 (UID/GID 1000 por defecto)
Puerto 8080 libre en el host (o el definido en variable PORT)
Navegador moderno con soporte ES modules (para uso directo del build estático)

Instalación con Docker Compose

Docker Compose (recomendado)

Crea un archivo docker-compose.yml con el siguiente contenido. Ajusta la ruta del volumen al directorio donde guardarás tu config.yml y assets.

services:
homer:
image: b4bz/homer
container_name: homer
volumes:
– /ruta/a/tu/config:/www/assets
ports:
– 8080:8080
user: 1000:1000
environment:
– INIT_ASSETS=1
restart: unless-stopped

Docker run (rápido)

Ejecución directa sin archivo compose. Reemplaza /ruta/a/tu/config por la ruta real en tu host.

docker run -d \
–name homer \
-p 8080:8080 \
–mount type=bind,source="/ruta/a/tu/config",target=/www/assets \
–restart=unless-stopped \
b4bz/homer:latest

Tarball precompilado (sin Docker)

Descarga la última versión, extrae, renombra config.yml.dist y sirve con cualquier servidor web estático.

wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip homer.zip -d homer
cd homer
cp assets/config.yml.dist assets/config.yml
# Ejemplo con http-server de Node
npx http-server -p 8080

Compilación manual (desarrollo)

Clona el repositorio, instala dependencias con pnpm y genera la build de producción en /dist.

git clone https://github.com/bastienwirtz/homer.git
cd homer
pnpm install
pnpm build
# Los archivos listos para servir están en ./dist

Acceder al proyecto

Interfaz web

Accede a http://<IP_DEL_HOST>:8080 (o el puerto configurado). Si definiste SUBFOLDER=/homer, la URL será http://<IP_DEL_HOST>:8080/homer.

Configuración

Edita el archivo assets/config.yml en el directorio montado. Los cambios se reflejan al recargar la página; no es necesario reiniciar el contenedor.

Variables de entorno principales

INIT_ASSETS=1 (por defecto) crea config.yml.dist y assets de ejemplo al iniciar. SUBFOLDER=/ruta para servir en subcarpeta. PORT=8080 puerto interno. IPV6_DISABLE=1 desactiva IPv6.

Casos de uso

Página de inicio personal para homelab con enlaces a servicios self-hosted (Portainer, Pi-hole, Home Assistant, Grafana, etc.)
Portal de acceso para equipos pequeños: documentación, repositorios, herramientas internas, monitorización
Dashboard de navegación en kioscos o pantallas de información en red local
Alternativa ligera a dashboards pesados cuando solo se necesita agrupación de enlaces y estado básico
Base para crear portales internos corporativos con marca propia mediante theming CSS

Configuración avanzada

Subcarpeta (reverse proxy)

Para servir Homer bajo una subruta (ej. https://midominio.com/homer), define la variable SUBFOLDER=/homer y configura el proxy inverso para reenviar el prefijo.

environment:
– SUBFOLDER=/homer

Cambio de puerto interno

Modifica el puerto que expone lighttpd dentro del contenedor. El mapeo de puertos en docker-compose debe coincidir.

environment:
– PORT=9090
ports:
– 9090:9090

UID/GID personalizados

Si el directorio de configuración pertenece a otro usuario, ajusta UID/GID para evitar problemas de permisos con INIT_ASSETS.

user: 1001:1001
environment:
– UID=1001
– GID=1001

Desactivar IPv6

En entornos sin soporte IPv6, evita errores de binding estableciendo IPV6_DISABLE=1.

environment:
– IPV6_DISABLE=1

Theming avanzado

Crea un archivo assets/themes/custom.css y referéncialo en config.yml (theme: custom). Permite sobrescribir variables CSS de Bulma y estilos propios.

# En config.yml
theme: custom
# assets/themes/custom.css
:root {
–primary: #2c3e50;
–background: #f5f6fa;
}

Gestión y mantenimiento

Actualizar imagen Docker

Descarga la última etiqueta y recrea el contenedor. Los datos persisten en el volumen montado.

docker compose pull
docker compose up -d

Backup de configuración

Copia de seguridad del directorio montado (config.yml, icons, themes, custom.js). No hay base de datos.

tar -czf homer-backup-$(date +%F).tar.gz /ruta/a/tu/config

Healthcheck integrado

El contenedor incluye healthcheck HTTP en el puerto configurado (cada 30s). Docker reiniciará automáticamente si falla.

# Ver estado
docker inspect –format='{{json .State.Health}}' homer | jq

Logs de lighttpd

Consulta los logs del servidor web embebido para diagnosticar errores de servir archivos estáticos.

docker logs homer

Stack técnico

Vue 3.5 (Composition API)
Vite 8 (build y dev server)
Bulma 1 (framework CSS)
FontAwesome 7 (iconos)
lodash.merge (utilidades)
yaml (parser YAML)
vite-plugin-pwa (PWA)
Node 24 (build stage)
pnpm 10 (gestor de paquetes)
lighttpd (servidor web producción)
Alpine Linux 3.23 (base imagen Docker)
Docker multi-stage build

Referencias oficiales

Repositorio oficial en GitHub: https://github.com/bastienwirtz/homer
Demo en vivo: https://homer-demo.netlify.app/
Imagen Docker en Docker Hub: https://hub.docker.com/r/b4bz/homer
Documentación de configuración: https://github.com/bastienwirtz/homer/blob/main/docs/configuration.md
Guía de theming: https://github.com/bastienwirtz/homer/blob/main/docs/theming.md
Tarjetas inteligentes (smart cards): https://github.com/bastienwirtz/homer/blob/main/docs/customservices.md
Licencia Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0

Apoya el canal GENBYTE

¿Te ha sido útil este contenido?

Suscríbete a YouTube
Newsletter GENBYTE
Ko-fi
Contacto: [email protected]