Gestión y personalización de contenedores

Disclaimer

Esta página está escrita para ayudar a los usuarios de todos los niveles de habilidad a aprovechar al máximo los contenedores de Docker en Unraid OS. Los consejos y las mejores prácticas provienen del equipo de Unraid, quienes aseguran que están adaptados a las necesidades de la mayoría de los usuarios. Sin embargo, tenga en cuenta que Docker está en constante evolución, por lo que para las características más recientes, configuraciones avanzadas o problemas de solución de problemas que van más allá de lo que cubre Unraid, siempre es una buena idea consultar la documentación oficial de Docker.

Antes de personalizar un contenedor de Docker en Unraid, es útil comprender las opciones básicas de configuración. Cada plantilla de contenedor proporciona una interfaz amigable para el usuario para configurar redes, almacenamiento y variables de entorno, permitiéndole ajustar el comportamiento del contenedor a sus necesidades sin usar herramientas complejas de línea de comandos.

Tipo de red

Unraid admite varios modos de red Docker. El tipo de red que elija determina cómo su contenedor se comunica con otros dispositivos y contenedores:

• Puente (predeterminado): El contenedor se coloca en una red interna de Docker. Solo los puertos que usted mapea explícitamente serán accesibles desde su servidor Unraid o LAN. Esta es la opción más segura y común para la mayoría de las aplicaciones.

• Anfitrión: El contenedor comparte la pila de red del servidor Unraid. Puede usar cualquier puerto disponible, pero debe asegurarse de que no haya conflictos de puertos con otros servicios. Use este modo solo si la aplicación requiere acceso directo a la red.

• Ninguno: El contenedor no tiene acceso a la red. Use esto para cargas de trabajo aisladas que no requieren conectividad de red.

• Personalizado (macvlan/ipvlan): El contenedor recibe su propia dirección IP en su LAN, lo que hace que parezca un dispositivo separado. Esto es útil para escenarios avanzados, pero puede requerir configuración adicional en su entorno de red.

consejo

El tipo de red predeterminado especificado en la plantilla del contenedor se recomienda para la mayoría de los usuarios.

Wi-Fi y Limitaciones de redes Docker

Docker tiene una limitación que impide que participe en dos redes que compartan el mismo subred. Si cambia entre una conexión alámbrica e inalámbrica, necesitará reiniciar Docker y reconfigurar todos los contenedores existentes para usar la nueva interfaz. Este cambio de configuración de red requiere la reconfiguración del contenedor.

Mapeo de volúmenes

Los mapeos de volumenes controlan cómo tu contenedor accede a los archivos en tu servidor de Unraid. Cada mapeo vincula una carpeta dentro del contenedor (ruta del contenedor) a una carpeta en tu servidor de Unraid (ruta del host).

• Ruta del contenedor: El directorio dentro del contenedor (por ejemplo, /config o /unraid_media).
• Ruta del anfitrión: El directorio en su servidor Unraid (por ejemplo, /mnt/user/appdata/myapp).
• Modo de acceso: Controla los permisos - solo lectura o lectura/escritura. Usa el modo más restrictivo que aún permita que el contenedor funcione.

Best práctica

Store application data (settings, libraries, etc.) outside the container, typically in the appdata user share. This share management approach keeps your data safe during updates or reinstalls.

nota

• Las rutas son sensibles a mayúsculas y minúsculas.
• Las rutas del contenedor deben comenzar con un /.
• Si usa un dispositivo no asignado como la ruta del anfitrión, configure el modo de acceso en una opción "Slave" para garantizar su detección correcta.
• Las rutas del anfitrión se crean automáticamente si no existen cuando el contenedor se inicia.
• La aparición de carpetas inesperadas en su servidor puede indicar una asignación mal configurada.

Mapeo de puertos

Las asignaciones de puertos determinan cómo se dirige el tráfico de red desde su servidor Unraid al contenedor.

• Red de puente: Puede asignar los puertos internos del contenedor a diferentes puertos del host. Por ejemplo, si tres contenedores utilizan el puerto 8000 internamente, puede asignarlos a 8000, 8001 y 8002 en el host.

• Red de host: El contenedor puede utilizar cualquier puerto disponible. Evite ejecutar múltiples contenedores con el mismo puerto para prevenir conflictos.

important

Solo modifique el valor del puerto del host. No cambie el puerto del contenedor a menos que sepa que la aplicación lo soporta.

La mayoría de las plantillas proporcionan valores predeterminados sensatos, pero puede añadir o ajustar asignaciones de puertos.

Variables de entorno

Las variables de entorno pueden personalizar cómo se comporta tu contenedor Docker en tiempo de ejecución. Permiten pasar pares clave-valor que tu aplicación en curso de contenedorización puede leer y utilizar.

Usos comunes para las variables de entorno

• Configurando la zona horaria
• Configurando identificadores de usuarios y grupos
• Especificando preferencias de idioma
• Ajustando configuraciones específicas de la aplicación, como claves API o conmutadores de funciones

Gestionando variables de entorno en el WebGUI

• Puede agregar, editar o eliminar variables de entorno en la pantalla de configuración del contenedor a través del WebGUI.
• Muchas plantillas de contenedor vienen con variables de entorno comunes que ya están establecidas, pero siempre puede agregar más si es necesario.
• Asegúrese de revisar la documentación específica de la aplicación para saber qué variables de entorno están disponibles y qué valores son válidos.

Examples de variables de entorno

• TZ=America/New_York: Esto establece la zona horaria del contenedor.
• PUID=99 y PGID=100: Estos establecen los IDs de usuario y grupo para permisos de archivo.
• UMASK=022: Esto controla los permisos de archivo predeterminados para archivos creados.
• API_KEY=your_api_key_here: Esto podría ser usado por una aplicación para autenticación con un servicio externo.

consejo

Utiliza variables de entorno para evitar codificar directamente información sensible o específica del entorno dentro de las imágenes de tu contenedor. Esta práctica mejora la portabilidad y seguridad de tus contenedores.

Creación y ejecución de contenedores

Una vez que haya configurado la red del contenedor, mapeos de volumen, mapeos de puertos y variables de entorno, estará listo para crear e iniciar su contenedor de Docker. Esta sección le guiará a través del proceso de creación, explicará cómo gestionar el orden de inicio y las dependencias, y proporcionará consejos para la personalización avanzada del inicio.

Creando un contenedor

Después de revisar sus ajustes de configuración en la plantilla del contenedor:

1. Haga clic en Crear para comenzar la descarga y configuración del contenedor.
   • Evite cerrar la ventana del navegador o navegar lejos hasta que el proceso se complete.
   • La descarga inicial para un nuevo repositorio puede tardar más que descargas subsiguientes.
2. Una vez el proceso haya finalizado, haga clic en Listo para volver a la página de Docker, donde puede gestionar o agregar más contenedores.

Planificación de su secuencia de inicio

Algunos contenedores dependen de otros para funcionar correctamente. Por ejemplo, una aplicación podría necesitar que un contenedor de base de datos se esté ejecutando primero, o un servicio podría requerir que un contenedor VPN esté activo antes de que comience.

Plan su inicio

• Identifique los contenedores que proporcionan servicios clave (como bases de datos, VPNs, o puertas de enlace de almacenamiento).
• Asegúrese de que los contenedores dependientes se inicien solo después de que sus requisitos previos estén funcionando y listos.
• Revise la documentación de cada contenedor para entender cualquier requerimiento específico de inicio.

---

Inicio avanzado de contenedores

Unraid le da un control flexible sobre qué contenedores inician automáticamente y en qué orden. Esto es especialmente útil si tiene contenedores que dependen de otros (como un servicio de base de datos o VPN).

Para asegurarse de que un contenedor se inicie automáticamente cuando el array se inicia:

1. Vaya a la pestaña Docker en el WebGUI.
2. Active el interruptor de Auto-inicio a ON para cada contenedor que desee que se inicie automáticamente.

Personalizar el orden de inicio y retrasos

Por defecto, Unraid inicia todos los contenedores de autoarranque lo más rápido posible, en el orden en que aparecen en la pestaña Docker. Puede personalizar este orden y agregar tiempos de espera entre los inicios de contenedores:

1. En la pestaña Docker, desbloquee la lista de contenedores usando el ícono de candado.
2. Arrastre y suelte los contenedores para reorganizar su orden.
3. Cambie a Vista Avanzada usando el interruptor en la parte superior derecha.
4. En la columna AutoStart, ingrese un tiempo de espera (en segundos) en el campo wait para cualquier contenedor que necesite tiempo extra antes de que el siguiente comience.
   • Use prueba y error para determinar los mejores tiempos de espera para su configuración.

consejo

Establecer el orden correcto y los tiempos de espera es especialmente importante para contenedores que dependen de servicios proporcionados por otros (por ejemplo, iniciar una base de datos antes que una aplicación que la use, o un VPN antes de apps dependientes).

Probando su secuencia de inicio

Aunque Unraid no tiene una función dedicada de "probar secuencia de inicio", puede simular y verificar su orden de inicio:

1. Detener todos los contenedores desde la pestaña Docker.
2. Inicie cada contenedor manualmente, en su orden planificado, usando el botón Iniciar.
3. Monitoree los registros de los contenedores y el comportamiento de la aplicación para asegurarse de que las dependencias se cumplan y los servicios se inicien como se espera.
4. Ajuste el orden de inicio o los tiempos de espera según sea necesario.

important

Pruebe su secuencia de inicio después de cambiar las dependencias de contenedores o agregar nuevos servicios, especialmente si su configuración depende de un temporizado específico de inicio.

---

Controlando tus contenedores

Una vez que haya creado e iniciado su contenedor de Docker, gestionarlo es fácil a través del WebGUI. Esta guía le llevará a través del uso del menú contextual, comprensión de los indicadores de salud del contenedor y acceso a los mapeos de volumen dentro de su contenedor.

Para acceder al menú contextual del contenedor, vaya a la pestaña Docker o Dashboard y haga clic en el ícono del contenedor que desea gestionar. Este menú ofrece acceso directo a acciones comunes:

Opciones	Descripción
WebUI	Abre la interfaz web del contenedor en una nueva pestaña del navegador (si está disponible).
Consola	Abre una interfaz de línea de comandos para interactuar directamente con el contenedor.
Detener	Detiene el contenedor en ejecución.
Pausa	Pausa el contenedor, deteniendo temporalmente todos los procesos.
Reiniciar	Reinicia el contenedor, aplicando cualquier cambio de configuración.
Registros	Muestra la salida de registros del contenedor para solución de problemas.
Editar	Cambia la configuración del contenedor, como mapeos de puertos o volúmenes. Los cambios se aplican inmediatamente después de guardarlos.
Eliminar	Elimina el contenedor. Puede elegir eliminar solo el contenedor o también borrar su imagen.
Página del proyecto	Abre la página del proyecto del contenedor para documentación y apoyo.
Soporte	Proporciona acceso a recursos de soporte y ayuda para el contenedor.
Más Información	Muestra información adicional sobre el contenedor y su configuración.

Indicador de estado

Encontrará un indicador de estado de color junto al ícono de cada contenedor:

• 🟢 Saludable: Indica que el contenedor está funcionando y responde como se espera.
• 🟡 No saludable: El contenedor está en ejecución pero ha fallado su chequeo de salud. Investigue los registros o configuración del contenedor para obtener más información.
• ⚪ Sin chequeo de salud: Esto significa que no hay un chequeo de salud configurado para el contenedor. Es común para muchas aplicaciones y no necesariamente un problema.

nota

Las verificaciones de salud son definidas por el autor del contenedor y pueden no estar presentes para todas las imágenes.

---

Asignaciones de volumen dentro de un contenedor

Al configurar su aplicación a través de su interfaz web, haga referencia a la ruta de contenedor que configuró durante la configuración - no a la ruta del anfitrión.

Por ejemplo, si mapeó /mnt/user/media en el anfitrión a /unraid_media en el contenedor, debe usar /unraid_media en la configuración de la aplicación.

Escenarios de ejemplo

Aquí hay algunos ejemplos que muestran configuraciones comunes de mapeo de rutas que los usuarios frecuentemente necesitan al configurar contenedores Docker. Demuestran cómo traducir entre las rutas del sistema de archivos del host de Unraid y las rutas internas del contenedor, ayudándole a configurar las aplicaciones correctamente.

• Servidor de medios: Ruta del host: /mnt/user/media
  Ruta del contenedor: /unraid_media

  En la aplicación, establece la ubicación de tu biblioteca de medios en /unraid_media.

• Almacenamiento de Appdata: Ruta del host: /mnt/user/appdata/myapp
  Ruta del contenedor: /config

  En la aplicación, utiliza /config para el almacenamiento de configuración.

• Múltiples user shares: Ruta del host: /mnt/user/media → Ruta del contenedor: /media
  Ruta del host: /mnt/user/data → Ruta del contenedor: /data

  Referencia /media o /data en la aplicación según sea necesario.

Best práctica

Siempre use el modo de acceso más restrictivo (solo lectura o lectura/escritura) que permita que su contenedor funcione correctamente.

---

Programación de inicio y parada

Unraid no admite de forma nativa acciones programadas para iniciar o detener contenedores de Docker, pero puede fácilmente automatizar este proceso usando el plug-in User Scripts. Este potente herramienta le permite ejecutar scripts personalizados en un horario, habilitando el control automático de sus contenedores.

Complemento User Scripts

El plug-in User Scripts le permite crear, gestionar y programar scripts shell personalizados directamente desde el WebGUI. Puede usarlo para diversas tareas de automatización, como iniciar o detener contenedores, realizar copias de seguridad de datos o ejecutar rutinas de mantenimiento.

• Instale el complemento desde la pestaña Apps si aún no lo ha hecho.
• Accédalo a través de Settings → User Scripts para crear y gestionar sus scripts.

Para aprender más sobre complementos, consulte Plugins.

Programación de acciones de contenedor

Para automatizar el inicio o detención de tus contenedores en un horario:

1. Instala el plugin de Scripts de Usuario desde la pestaña Apps.
2. Navega a Ajustes → Scripts de Usuario.
3. Cree un nuevo script para cada horario único. Puede incluir comandos para múltiples contenedores en un único script si comparten el mismo horario.
4. Configura el horario usando el menú desplegable o utiliza una expresión cron personalizada para opciones de tiempo más avanzadas.
5. Haz clic en Aplicar para guardar y activar tu script.

consejo

Las expresiones Cron permiten una planificación flexible más allá de las opciones integradas. Por ejemplo, 0 3 * * 1 ejecuta su script a las 3:00 AM cada lunes.

Ejemplos de comandos

Iniciar contenedor

Para iniciar un contenedor, usa el comando:

docker start "nombre-del-contenedor"

Reemplaza "nombre-del-contenedor" con el nombre real como se muestra en la pestaña Docker.

Detener contenedor

Para detener un contenedor, usa el comando:

docker stop "nombre-del-contenedor"

Reemplaza "nombre-del-contenedor" con el nombre real como se muestra en la pestaña Docker.

Reiniciar contenedor

Para reiniciar un contenedor (útil después de actualizar configuraciones o solucionar problemas):

docker restart "nombre-del-contenedor"

Reemplaza "nombre-del-contenedor" con el nombre real como se muestra en la pestaña Docker.

Verificar estado del contenedor

Para verificar si un contenedor está en ejecución:

docker ps --filter "name=nombre-del-contenedor"

Esto enumerará el contenedor si está actualmente en ejecución.

Mostrar registros del contenedor

Para ver los registros de un contenedor (útil para solucionar problemas):

registros de Docker "nombre-del-contenedor"

Esto muestra la salida reciente de registros para el contenedor especificado.

consejo

Puedes encontrar el nombre del contenedor en la pestaña Docker o viendo el comando docker run en la pantalla de configuración del contenedor.