Migración de Easypanel a Tugport: cinco fallos y lecciones aprendidas

El 24 de octubre, un desarrollador migró su servidor principal de producción desde la plataforma de despliegue Easypanel a Tugport, una nueva herramienta que está construyendo. La migración implicó mover 14 proyectos y 57 servicios, incluyendo bases de datos, blogs y bots, mediante una única instrucción de línea de comandos. Aunque la transición fue en gran medida exitosa, surgieron cinco problemas específicos durante el proceso, lo que puso de manifiesto las trampas comunes en las migraciones automatizadas de infraestructura.

Qué ocurrió

El proceso de migración comenzó con una ejecución de prueba (dry run) para mapear los servicios sin realizar cambios, seguido de la ejecución real del comando tugport migrate easypanel. Tugport, un binario basado en Rust que se ejecuta junto a Docker, importó el estado de Easypanel, incluidos proyectos, variables de entorno, dominios y certificados. A continuación, movió las bases de datos una por una, asegurándose de que la instancia antigua se detuviera antes de que la nueva comenzara en el mismo directorio de datos para evitar la corrupción. Las aplicaciones se iniciaron junto a sus contrapartes antiguas utilizando exactamente las mismas imágenes, evitando reconstrucciones durante el cambio.

El cambio de tráfico se produjo cuando el proxy de Tugport tomó el control de los puertos 80 y 443 del proxy Traefik de Easypanel en medio segundo. Un mecanismo de seguridad garantizó que, si el nuevo proxy no respondía dentro de 30 segundos, el proxy antiguo retomaría el control. El sistema registró cada paso, permitiendo la reanudación o la reversión si era necesario. Los volúmenes y los montajes bind permanecieron en su lugar, y los certificados fueron importados en lugar de ser reemitidos. En última instancia, 54 servicios funcionaban en Tugport, mientras que tres servicios previamente escalados hacia abajo permanecían detenidos.

A pesar del diseño cuidadoso, aparecieron cinco errores durante esta primera migración en producción. Primero, las plantillas de variables de entorno de Easypanel, como $(PROJECT_NAME), se copiaron literalmente en lugar de resolverse, lo que requirió corrección manual. Segundo, los dominios de marcador de posición asignados por Easypanel confundieron las comprobaciones de estado de Tugport, haciendo que los servicios no web se colgaran esperando respuestas HTTP. Tercero, se produjo un conflicto de subredes de red porque la pila antigua del runner de CI aún mantenía su red fija, lo que exigió una limpieza manual. Cuarto, se mostró un código de error inofensivo durante las repeticiones, causando alarmas innecesarias. Finalmente, los bots de Telegram que utilizan polling experimentaron conflictos temporales ya que tanto las instancias antiguas como las nuevas intentaban obtener actualizaciones simultáneamente.

Detalles clave

• La migración movió 57 servicios en 14 proyectos, incluyendo bases de datos Postgres, MySQL y Mongo.
• Se identificaron cinco errores específicos: copia literal de plantillas de variables de entorno, fallos en las comprobaciones de estado debido a dominios de marcador de posición, superposiciones de pools de red, registro de errores cosméticos y conflictos de polling de bots.
• Las comprobaciones de estado de las bases de datos inicialmente agotaban el tiempo de espera bajo alta carga porque se ejecutaban cada 5 segundos con un timeout de 5 segundos; estos se ajustaron a intervalos de 30 segundos con timeouts de 15 segundos.
• Una etiqueta flotante de Docker (mysql:9) causó una actualización involuntaria de versión menor de 9.7.0 a 9.7.4, resultando en tres minutos de inactividad.
• El migrador ahora fija las imágenes de base de datos a sus versiones exactas y resuelve automáticamente las plantillas de variables de entorno.

Contexto

Tugport es un panel de despliegue autoalojado escrito en Rust. Opera junto a Docker en un servidor propiedad del usuario, gestionando compilaciones desde pushes de git, terminación HTTPS y gestión de servicios. A diferencia de algunas plataformas que abstraen la infraestructura subyacente, Tugport está diseñado para la transparencia y el control, ofreciendo claves API con alcance limitado para agentes de IA y herramientas de migración integradas para competidores como Easypanel y Coolify. La herramienta es de código abierto bajo la licencia MIT.

Easypanel es un popular panel de gestión de servidores que simplifica el despliegue de aplicaciones mediante Docker. Utiliza Traefik como proxy inverso y gestiona los servicios a través de una interfaz gráfica. Al migrar entre tales paneles, el desafío no radica solo en mover datos, sino en traducir matices de configuración, ajustes de red y lógica de comprobaciones de estado que a menudo son implícitos en la plataforma original.

Por qué importa

Para equipos que ejecutan software autoalojado, este caso de estudio ilustra que las migraciones automatizadas rara vez son fluidas. Incluso con una herramienta bien diseñada, las diferencias en cómo las plataformas manejan las variables de entorno, la red interna y las comprobaciones de estado pueden causar interrupciones del servicio. Comprender estos modos de fallo ayuda a los ingenieros a anticipar riesgos al cambiar de proveedores o herramientas de infraestructura. Enfatiza la necesidad de pruebas exhaustivas y la importancia de leer cuidadosamente las salidas de las ejecuciones de prueba antes de aplicar cambios en vivo.

El incidente con la etiqueta flotante de Docker sirve como recordatorio crítico para entornos de producción. Confiar en etiquetas mutables como latest o etiquetas que solo indican la versión mayor puede llevar a actualizaciones inesperadas y tiempos de inactividad. Fijar las imágenes a versiones específicas garantiza reproducibilidad y estabilidad, una buena práctica que a menudo se pasa por alto hasta que una migración fuerza una reevaluación de las configuraciones de despliegue.

Qué puedes hacer

• Ejecuta siempre primero una migración de prueba (dry run) para identificar problemas de mapeo, configuraciones faltantes y servicios que no se transferirán automáticamente.
• Fija todas las imágenes de contenedor a versiones específicas en lugar de usar etiquetas flotantes para evitar actualizaciones no deseadas durante los redespliegues.
• Revisa y ajusta los intervalos y tiempos de espera de las comprobaciones de estado después de la migración, especialmente si la nueva plataforma tiene diferentes patrones de uso de recursos predeterminados.
• Verifica manualmente las variables de entorno que usan sintaxis de plantilla, ya que las herramientas automatizadas pueden no resolver correctamente los marcadores de posición específicos de la plataforma.
• Planifica conflictos temporales en servicios basados en polling, como bots de chat, asegurándote de que las instancias antiguas estén completamente detenidas antes de que las nuevas comiencen a procesar solicitudes.
• Limpia redes antiguas y recursos no utilizados después de una migración exitosa para liberar espacio en disco y prevenir conflictos de subredes.