Vídeo tutorial en YouTube

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

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

Homarr es una aplicación de panel de control (dashboard) diseñada para entornos de autoalojamiento (self-hosting). Permite centralizar el acceso a servicios, aplicaciones y recursos mediante una interfaz visual configurable. El proyecto está desarrollado en TypeScript, utiliza Next.js 16 como framework web, React 19 para la interfaz de usuario y Mantine como biblioteca de componentes. Se distribuye como imagen Docker multi-arquitectura y expone el puerto 7575. La persistencia de datos se realiza por defecto mediante SQLite (better-sqlite3), con soporte opcional para PostgreSQL. Incluye autenticación basada en credenciales, cifrado de secretos de integración y un CLI integrado para tareas de administración.

Características principales

Requisitos del sistema

• Motor de contenedores compatible con OCI (Docker, Podman)
• Arquitectura linux/amd64 o linux/arm64 (imagen multi-plataforma)
• Mínimo 512 MB RAM disponibles para el contenedor
• Volumen persistente para /appdata (base de datos SQLite, certificados, configuración Redis)
• Puerto 7575 accesible en el host o red overlay
• Generación previa de AUTH_SECRET y SECRET_ENCRYPTION_KEY (64 caracteres hexadecimales cada uno)

Instalación con Docker Compose

Despliegue con Docker (imagen oficial)

La imagen oficial se publica en GitHub Container Registry. El siguiente comando crea un contenedor con volumen persistente, variables de entorno obligatorias y publicación del puerto 7575. Los secretos AUTH_SECRET y SECRET_ENCRYPTION_KEY deben generarse previamente con `openssl rand -hex 32`.

Variables de entorno obligatorias

AUTH_SECRET y SECRET_ENCRYPTION_KEY son requeridos al primer arranque. La aplicación rechazará valores vacíos o inválidos. DB_URL debe ser una ruta absoluta dentro del volumen /appdata para que migraciones y aplicación compartan el mismo archivo SQLite.

Acceder al proyecto

Interfaz web

Accede al dashboard en http://<host>:7575 tras el arranque del contenedor. En el primer acceso se solicita crear la cuenta de administrador (email y contraseña).

CLI integrado

Ejecuta comandos administrativos dentro del contenedor: `docker exec -it homarr homarr –help` muestra subcomandos disponibles (migraciones, usuarios, secretos, etc.).

Casos de uso

• Portal único de acceso a servicios autoalojados (media servers, descargas, monitorización, infraestructura)
• Panel de control para homelabs con visualización de estado de contenedores Docker, máquinas virtuales Proxmox, clústeres Kubernetes
• Frontend unificado para stacks *arr (Sonarr, Radarr, Lidarr, Readarr, Prowlarr) con acciones rápidas y métricas
• Dashboard familiar o de equipo con autenticación y tableros personalizados por usuario
• Punto de entrada seguro detrás de proxy inverso (Traefik, Nginx Proxy Manager, Caddy) con TLS terminado en el edge

Configuración avanzada

Base de datos PostgreSQL externa

Para usar PostgreSQL en lugar de SQLite, define DB_DRIVER=node-postgres y DB_URL con la cadena de conexión completa. Las migraciones se aplican automáticamente al arranque.

Redis externo

Desactiva la instancia embebida y conecta a un servidor Redis externo (útil para alta disponibilidad o clústeres).

Certificados de confianza personalizados

Monta un directorio con certificados CA personalizados y define LOCAL_CERTIFICATE_PATH para que Homarr valide conexiones TLS a servicios internos con PKI propia.

Sockets Docker múltiples

Permite conectar a varios runtimes de contenedores (Docker + Podman) simultáneamente mediante DOCKER_SOCKET_PATHS.

Modo demostración

Activa DEMO_MODE=true para sembrar un usuario demo (demo/demo), un tablero de ejemplo y una integración mock. DEMO_READ_ONLY=false permite escritura en el modo demo.

Gestión y mantenimiento

Actualización de imagen

Descarga la nueva etiqueta y recrea el contenedor preservando el volumen /appdata. Las migraciones de base de datos se ejecutan automáticamente al iniciar la versión nueva.

Migraciones de base de datos manuales

Ejecuta migraciones pendientes sin reiniciar la aplicación usando el CLI interno.

Copia de seguridad de la base de datos SQLite

Copia el archivo de base de datos desde el volumen persistente mientras el contenedor está detenido o en modo solo lectura para evitar corrupción.

Rotación de secretos

Genera nuevos AUTH_SECRET y SECRET_ENCRYPTION_KEY, actualiza las variables de entorno y reinicia. Nota: la rotación de SECRET_ENCRYPTION_KEY invalida secretos de integración cifrados previamente; se requerirá reconfigurarlos.

Limpieza de caché Redis

Vacía la base de datos Redis embebida o externa para forzar recarga de datos de integraciones.

Stack técnico

• TypeScript
• Next.js 16 (App Router, Server Components)
• React 19
• Mantine UI 9 (componentes, formularios, gráficos, notificaciones)
• Bun 1.4 (gestor de paquetes, runtime de build)
• Node.js 24.18 (runtime de producción)
• SQLite (better-sqlite3) / PostgreSQL (node-postgres)
• Drizzle ORM (consultas tipadas, migraciones)
• NextAuth v5 / @auth/core (autenticación)
• Redis (ioredis) – caché y colas
• Nginx (proxy inverso, TLS, trusted proxies)
• Docker multi-stage (Alpine 3.24 runner)
• tRPC (API tipada end-to-end)
• TanStack Query (estado servidor, persistencia)
• Zod (validación de esquemas)
• Tailwind CSS (utilidades, vía postcss-preset-mantine)
• Vitest / Playwright (tests unitarios, integración, E2E)
• Turbo (monorepo, build pipeline)
• Semantic Release (versionado automático, changelog)

Apoya el canal GENBYTE

Sígueme en mis redes sociales