Cómo autoalojar Homarr en 2026: paneles, secretos y widgets en tiempo real

Un contenedor de Homarr puede aparecer en estado correcto aunque el funcionamiento que les importa a los usuarios esté fallando. En Homarr, este fallo oculto suele deberse a que los widgets no pueden acceder a los servicios porque utilizan direcciones locales del host. Esta guía considera como prueba de aceptación «crear un panel, añadir un widget de servicio, configurar una integración con credenciales y confirmar el estado y la búsqueda en tiempo real después de reiniciar», y diseña el despliegue partiendo de ese resultado.

Homarr cumple una función específica en la arquitectura: es un panel con búsqueda y widgets en tiempo real para servicios autoalojados. Por tanto, la cuestión en producción no es si el puerto 7575 responde una vez, sino si el estado, las dependencias y la dirección pública siguen siendo coherentes después de un reinicio, una actualización y una restauración.

Define primero el éxito de Homarr

No dejes que la imagen de Homarr determine por accidente la arquitectura de producción. La imagen proporciona un proceso en el puerto 7575; el almacenamiento, el enrutamiento y los requisitos externos siguen necesitando ciclos de vida definidos de forma deliberada. El requisito del entorno de ejecución local son los datos persistentes de la aplicación y las credenciales para las integraciones en tiempo real. Esto debe formar parte del plan de capacidad y montajes, con un responsable y un límite medible.

El despliegue estará listo para pruebas más profundas cuando pueda crear un panel, añadir un widget de servicio, configurar una integración con credenciales y confirmar el estado y la búsqueda en tiempo real después de reiniciar. Sigue la transacción en los logs y observa la distribución de solicitudes de los widgets, la latencia de las API posteriores, el tamaño de los datos de la aplicación y los clientes simultáneos del panel. Estas observaciones revelan si la topología actual aísla el componente adecuado.

Ensaya el cambio de Homarr que entraña riesgos

Un contenedor en estado correcto es necesario, pero no suficiente. El indicador de nivel de servicio es la finalización correcta de «crear un panel, añadir un widget de servicio, configurar una integración con credenciales y confirmar el estado y la búsqueda en tiempo real después de reiniciar», mientras que las señales de presión más probables son la distribución de solicitudes de los widgets, la latencia de las API posteriores, el tamaño de los datos de la aplicación y los clientes simultáneos del panel.

El control de cambios es importante porque las migraciones de esquema de Homarr y la continuidad de la clave de cifrado pueden afectar a las credenciales de integración almacenadas. Conserva la imagen anterior, prueba las migraciones con una copia del estado y documenta si se admite la reversión después de mover el esquema. Si los widgets no pueden acceder a los servicios porque utilizan direcciones locales del host, diagnostica el primer límite que difiera del entorno operativo.

Registra un despliegue de Homarr conocido como correcto

No utilices el tráfico del primer usuario como prueba de aceptación de Homarr. Prepara un estado de ejemplo inocuo y ejecuta la acción completa «crear un panel, añadir un widget de servicio, configurar una integración con credenciales y confirmar el estado y la búsqueda en tiempo real después de reiniciar». Anota la URL pública exacta, el resultado, la referencia de la imagen y el intervalo de logs asociados a la ejecución.

Sustituye el contenedor y repite la prueba sin reconstruir los datos. Después, realiza una recuperación en un host vacío; la condición de recuperación es que vuelvan los paneles, los usuarios, las integraciones y los recursos personalizados, y que los widgets con credenciales vuelvan a conectarse. Observa la distribución de solicitudes de los widgets, la latencia de las API posteriores, el tamaño de los datos de la aplicación y los clientes simultáneos del panel en cada ejecución, y define una alerta en torno a la degradación de la transacción, no de las métricas de un contenedor inactivo.

Una última comprobación debe fallar a propósito: envía una entrada inocua cerca del límite de recursos o formato asociado a este límite: los widgets no pueden acceder a los servicios porque utilizan direcciones locales del host. Verifica que el mensaje resultante de Homarr identifique el límite relevante en lugar de provocar el borrado de datos o un reinicio interminable. Restablece la condición válida y confirma que la misma transacción de ejemplo se completa correctamente. Incluye este breve ensayo en la lista de comprobación de la versión.

Ejecuta la primera instancia con una configuración similar a producción

El primer contenedor debe ser fácil de eliminar y recrear. Mantén los datos fuera de la capa escribible, enlaza el puerto 7575 únicamente donde pueda acceder el proxy y proporciona la configuración en tiempo de ejecución.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Fija la versión de la imagen después de la prueba inicial. Lee el primer error de arranque en lugar del mensaje final de reinicio, verifica cada montaje con docker inspect y sigue los logs mientras creas un panel, añades un widget de servicio, configuras una integración con credenciales y confirmas el estado y la búsqueda en tiempo real después de reiniciar. Esta secuencia distingue un comando de imagen incorrecto de un problema de dependencia o permisos.

Los volúmenes son solo la primera capa de recuperación

En Homarr, la seguridad de la redistribución comienza por los paneles, usuarios, integraciones, secretos y recursos personalizados. Monta /appdata antes del arranque inicial, escribe datos de ejemplo inocuos y sustituye el contenedor para demostrar que esa ruta es realmente persistente. Prueba la ruta sustituyendo el contenedor mientras existan datos de ejemplo inocuos; así descubrirás los montajes apuntados un directorio por encima o por debajo del correcto.

Después, prueba la recuperación ante desastres en un host vacío. Cuando sea necesario, utiliza una exportación de la base de datos coherente con la aplicación y verifica que vuelvan los paneles, usuarios, integraciones y recursos personalizados, y que los widgets con credenciales vuelvan a conectarse. La guía de copias de seguridad de bases de datos restauradas ofrece un objetivo más sólido que limitarse a comprobar que se ha creado un archivo de archivo.

Evita que el éxito del proxy oculte un fallo de la aplicación

El navegador, el cliente de API y Homarr deben coincidir en un mismo origen. Para conseguirlo, configura el nombre de host HTTPS externo y los orígenes permitidos. Conserva el host y el protocolo originales, y mantén el puerto 7575 inaccesible como dirección pública alternativa.

La guía de solución de problemas de un sitio caído ayuda a distinguir entre una ruta inaccesible y una aplicación que responde. Esa distinción es importante aquí: los widgets no pueden acceder a los servicios porque utilizan direcciones locales del host. Los cambios en el ingreso solo solucionan el primer caso; el segundo requiere inspeccionar los logs, el estado o la carga de trabajo de Homarr.

Cierra el acceso temporal de configuración

Un despliegue seguro de Homarr comienza eliminando privilegios. Evita cambiar la clave de cifrado después de almacenar secretos de integración; en su lugar, mantén estable SECRET_ENCRYPTION_KEY, protege la edición de los paneles y limita las credenciales de cada widget.

Genera SECRET_ENCRYPTION_KEY una sola vez, mantenla fuera de Git y consérvala junto con el manifiesto de recuperación, porque cambiarla puede invalidar el estado de la aplicación cifrado o firmado. Restringe las rutas administrativas, utiliza DNS privado para las dependencias y revisa cada montaje enlazado. Cuando los logs se envíen a un sistema centralizado, filtra los secretos y el contenido privado antes de que salgan del servidor.

Traslada el trabajo de infraestructura repetible a Dockup

En Homarr, Dockup resulta más útil en el límite entre una imagen y un servicio duradero. Mantiene asociados la ruta al puerto 7575, TLS, los valores secretos y el almacenamiento durante las sustituciones de contenedores, tanto si el cómputo pertenece a Dockup como si pertenece a tu servidor conectado.

Termina con conocimiento de la aplicación: configura el nombre de host HTTPS externo y los orígenes permitidos; confirma el requisito local —datos persistentes de la aplicación y credenciales para las integraciones en tiempo real—; y ejecuta esta verificación: crea un panel, añade un widget de servicio, configura una integración con credenciales y confirma el estado y la búsqueda en tiempo real después de reiniciar. Conserva el resultado como comprobación de despliegue para que la próxima actualización de la imagen se evalúe por su comportamiento y no por el estado del contenedor.

Preguntas frecuentes

¿Qué necesita Homarr para un despliegue en producción?

Enruta el contenedor de Homarr en el puerto 7575 a través de un único origen HTTPS. El requisito del entorno de ejecución local son los datos persistentes de la aplicación y las credenciales para las integraciones en tiempo real. No consideres Homarr listo hasta que puedas crear un panel, añadir un widget de servicio, configurar una integración con credenciales y confirmar el estado y la búsqueda en tiempo real después de reiniciar.

¿Qué datos de Homarr deben incluirse en una copia de seguridad?

Haz persistente /appdata e incluye los paneles, usuarios, integraciones, secretos y recursos personalizados en el mismo manifiesto de recuperación. Una restauración limpia de Homarr solo se completa correctamente cuando vuelven los paneles, usuarios, integraciones y recursos personalizados, y los widgets con credenciales vuelven a conectarse.

¿Homarr necesita HTTPS detrás de un proxy inverso?

Utiliza HTTPS para el origen público de Homarr y mantén el puerto 7575 en la ruta interna. Aplica correctamente la configuración de Homarr: establece el nombre de host HTTPS externo y los orígenes permitidos. En Homarr, HTTPS protege las credenciales o el contenido de los usuarios durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo se debe probar una actualización de Homarr?

Restaura el estado actual de Homarr en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención, porque las migraciones de esquema de Homarr y la continuidad de la clave de cifrado pueden afectar a las credenciales de integración almacenadas. Conserva la imagen anterior de Homarr hasta comprender los límites de migración de datos y reversión.