Vídeo tutorial en YouTube

Mira el vídeo completo sobre cómo instalar y usar Homarr: Panel de control moderno para servicios autohospedados en el canal GENBYTE:

¿Qué es Homarr: Panel de control moderno para servicios autohospedados?

Homarr es un dashboard moderno y fácil de usar diseñado para centralizar el acceso a servicios autohospedados. Desarrollado por Homarr Labs, el proyecto destaca por su enfoque en la experiencia de usuario: configuración mediante arrastrar y soltar, sin necesidad de editar archivos YAML, autenticación integrada lista para usar y una biblioteca de más de 20.000 iconos. La versión actual es 2.4.1, licenciada bajo Apache-2.0, y está construida con TypeScript, Next.js 16, React 19 y Bun como gestor de paquetes y runtime. El stack incluye Drizzle ORM con better-sqlite3 por defecto, Redis para caché y colas, Nginx como proxy inverso interno y tRPC para la comunicación tipo-segura entre cliente y servidor.

Características principales

Requisitos del sistema

• Docker Engine 24+ o Docker Compose v2+
• Arquitectura compatible: linux/amd64, linux/arm64 (imagen multi-plataforma)
• Mínimo 512 MB RAM disponibles para el contenedor (recomendado 1 GB+)
• Volumen persistente para /appdata (base de datos SQLite, certificados, configuración Redis)
• Puertos: 7575/tcp expuesto en el host
• Generación previa de claves: AUTH_SECRET y SECRET_ENCRYPTION_KEY (64 caracteres hex cada una, openssl rand -hex 32)

Instalación con Docker Compose

Preparar variables de entorno

Crea un archivo .env a partir de .env.example y genera los secretos obligatorios. No reutilices valores ni subas el .env a control de versiones.

Desplegar con Docker Compose (recomendado)

El proyecto no incluye docker-compose.yml en el repositorio principal; la documentación oficial en homarr.dev provee plantillas para Docker Compose, Portainer, Kubernetes y TrueNAS. El ejemplo mínimo usando la imagen oficial ghcr.io/homarr-labs/homarr:latest es:

Iniciar el servicio

Levanta el contenedor en segundo plano. La imagen ejecuta migraciones automáticas al arranque mediante entrypoint.sh.

Verificar logs de arranque

Confirma que la aplicación inicia correctamente, genera la base de datos y expone el puerto.

Acceder al proyecto

Interfaz web

Accede al dashboard en http://<IP_HOST>:7575. En el primer acceso se solicita crear la cuenta de administrador (usuario/contraseña) si no existe ninguna.

CLI integrada

El contenedor expone el comando `homarr` para tareas de migración, seed y gestión de usuarios. Ejemplo: `docker exec -it homarr homarr db:migrate`.

Casos de uso

• Portal único para acceder a todos los servicios autohospedados de una red local o VPS
• Panel de control para stacks *arr (Sonarr, Radarr, Lidarr, Prowlarr, Bazarr, Readarr) con widgets de estado y acciones rápidas
• Monitorización visual de contenedores Docker, máquinas virtuales Proxmox y clústeres Kubernetes
• Gestión centralizada de descargas (qBittorrent, Transmission, Deluge) y bibliotecas multimedia (Jellyfin, Plex, Immich)
• Dashboard familiar con autenticación sencilla y modo demo para pruebas sin compromiso

Configuración avanzada

Base de datos PostgreSQL externa

Para entornos de alta disponibilidad o múltiples réplicas, configura DB_DRIVER=node-postgres y DB_URL con la cadena de conexión. Requiere ejecutar migraciones manualmente o habilitar auto-migración en el entrypoint.

Redis externo

Desactiva el Redis embebido y apunta a una instancia externa para persistencia de sesiones y colas compartidas.

Certificados TLS locales

Monta un directorio con certificados de confianza y configura LOCAL_CERTIFICATE_PATH para que Homarr valide conexiones HTTPS a servicios internos con CA privada.

Socket Docker / Podman múltiple

Permite conectar a varios runtimes de contenedores simultáneamente mediante DOCKER_SOCKET_PATHS.

Modo demo

Activa DEMO_MODE=true para sembrar un usuario demo/demo, tablero de ejemplo e integración mock. Útil para evaluación sin configuración.

Proxy inverso externo (Traefik, Nginx Proxy Manager, Caddy)

Homarr detecta cabeceras X-Forwarded-* automáticamente. Configura BASE_URL con la URL pública (https://homarr.ejemplo.com) para que OAuth, MCP y redirecciones funcionen correctamente detrás de proxy.

Gestión y mantenimiento

Actualizar imagen

Descarga la última etiqueta y recrea el contenedor manteniendo el volumen /appdata.

Ejecutar migraciones manualmente

Si se actualiza la versión y hay cambios de esquema, fuerza la migración desde la CLI interna.

Backup de la base de datos

Copia el archivo SQLite del volumen persistente. Para PostgreSQL usa pg_dump.

Rotación de secretos

Genera nuevos AUTH_SECRET y SECRET_ENCRYPTION_KEY, actualiza .env y reinicia. Los secretos de integración almacenados dejarán de ser legibles; vuelve a configurarlos en la UI.

Limpieza de caché Redis

Vacía la base de datos Redis embebida si hay inconsistencias de sesión o colas atascadas.

Stack técnico

• TypeScript 7
• Next.js 16 (App Router, standalone output)
• React 19
• Bun 1.4.2 (package manager & runtime)
• Turbo (monorepo build system)
• Drizzle ORM
• better-sqlite3 (SQLite driver)
• node-postgres (PostgreSQL driver opcional)
• Redis 7 (ioredis client)
• Nginx (reverse proxy interno, plantilla con envsubst)
• next-auth v5 beta (autenticación)
• tRPC 11 (API tipo-segura)
• TanStack Query 5 (estado servidor)
• Mantine UI 9 (componentes)
• Tabler Icons / Lucide (iconografía)
• Zod 4 (validación)
• Mermaid (diagramas)
• Vitest / Playwright (testing)
• Docker multi-stage (Node 24 Alpine + Bun + Alpine runner)

Apoya el canal GENBYTE

Sígueme en mis redes sociales