Gestión y personalización de contenedores

:::caution[Disclaimer]

Esta página está redactada para ayudar a usuarios de todos los niveles a aprovechar al máximo los contenedores Docker en Unraid OS. Los consejos y 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, ten en cuenta que Docker está en constante evolución, por lo que para obtener las funciones más actualizadas, configuraciones avanzadas o resolver problemas que van más allá de lo que Unraid cubre, siempre es una buena idea consultar la documentación oficial de Docker.

:::

Antes de personalizar un contenedor Docker en Unraid, es útil entender las opciones básicas de configuración. Cada plantilla de contenedor proporciona una interfaz fácil de usar para configurar la red, el almacenamiento y las variables de entorno, permitiéndote adaptar el comportamiento del contenedor a tus necesidades sin necesidad de usar herramientas de línea de comandos complejas.

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 Networking de Docker

Docker tiene una limitación que le impide participar en dos redes que comparten el mismo subred. Si cambias entre una conexión cableada y una conexión inalámbrica, necesitarás reiniciar Docker y reconfigurar todos los contenedores existentes para usar la nueva interfaz. Este cambio de configuración de red requiere una reconfiguración de contenedores.

Mapeos de Volumen

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

Almacene los datos de la aplicación (configuraciones, bibliotecas, etc.) fuera del contenedor, típicamente en el appdata user share. Este enfoque de administración de shares mantiene sus datos seguros durante las actualizaciones o reinstalaciones.

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.

Mapeos de Puerto

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

Utilice variables de entorno para evitar codificar de manera fija información sensible o específica del entorno dentro de las imágenes de sus contenedores. Esta práctica mejora la portabilidad y la seguridad de sus contenedores.

Creación y ejecución de contenedores

Una vez que hayas configurado la red del contenedor, los mapeos de volumen, los mapeos de puerto y las variables de entorno, estarás listo para crear y lanzar tu contenedor Docker. Esta sección te guiará a través del proceso de creación, explicará cómo gestionar el orden de inicio y las dependencias, y proporcionará consejos para 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 un contenedor de base de datos en funcionamiento primero, o un servicio podría requerir un contenedor VPN activo antes de que comience.

Plan tu 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 te brinda control flexible sobre qué contenedores comienzan automáticamente y en qué orden. Esto es especialmente útil si tienes 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 inicio automático tan rápidamente como sea posible, en el orden en que aparecen en la pestaña Docker. Puedes personalizar este orden y añadir 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 hayas creado e iniciado tu contenedor Docker, gestionarlo es fácil a través del WebGUI. Esta guía te guiará en el uso del menú contextual, la comprensión de los indicadores de salud del contenedor y el acceso a los mapeos de volumen dentro de tu contenedor.

Para acceder al menú contextual del contenedor, dirígete a la pestaña Docker o Dashboard y haz clic en el icono del contenedor que deseas gestionar. Este menú ofrece un acceso sencillo a acciones comunes:

Opción	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.
Pausar	Pausa el contenedor, deteniendo temporalmente todos los procesos.
Reiniciar	Reinicia el contenedor, aplicando cualquier cambio de configuración.
Registros	Muestra la salida del registro del contenedor para resolución de problemas.
Editar	Cambia la configuración del contenedor, como mapeos de puerto o volumen. Los cambios se aplican inmediatamente después de guardar.
Eliminar	Elimina el contenedor. Puedes 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 soporte.
Soporte	Proporciona acceso a recursos 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 verificación de estado. Investiga los registros o la configuración del contenedor para más información.
• ⚪ Sin verificación de estado: Esto significa que no se ha configurado una verificación de estado 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í tienes 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ándote a configurar aplicaciones correctamente.

• Servidor multimedia: 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, usa /config para el almacenamiento de configuración.

• Multiple user shares: Host path: /mnt/user/media → Container path: /media
  Host path: /mnt/user/data → Container path: /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 acciones programadas para iniciar o detener contenedores Docker, pero puedes automatizar fácilmente este proceso mediante el plugin Scripts de Usuario. Esta poderosa herramienta te permite ejecutar scripts personalizados en un horario, habilitando el control automático de tus contenedores.

Complemento User Scripts

El plugin Scripts de Usuario te permite crear, gestionar y programar scripts de shell personalizados directamente desde el WebGUI. Puedes usarlo para varias tareas de automatización, como iniciar o detener contenedores, respaldar 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. Crea un nuevo script para cada horario único. Puedes incluir comandos para múltiples contenedores en un solo 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 programación flexible más allá de las opciones integradas. Por ejemplo, 0 3 * * 1 ejecuta tu script a las 3:00 AM todos los lunes.

Ejemplos de comandos

Iniciar contenedor

Para iniciar un contenedor, usa el comando:

docker start "container-name"

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 "container-name"

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 "container-name"

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=container-name"

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):

docker logs "container-name"

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.