Guía completa para depurar y resolver los problemas más comunes al desplegar Django en un entorno con contenedores
TLDR
Se invirtieron 6 horas depurando un despliegue roto de un backend Django. Los problemas incluyeron migraciones faltantes, errores de autenticación SSH, desajustes de tipo de base de datos, dependencias ausentes y una imagen desactualizada en ECR. Aquí documentamos la solución completa con los comandos clave utilizados.
Escenario del desastre
Te piden arreglar un backend roto y los logs parecen jeroglíficos. Error típico: Django no encuentra el nodo de migración padre de una app que ni siquiera tiene migraciones generadas.
Fase de descubrimiento del problema
Primer indicio con docker-compose logs backend: dependencia de una app sin migraciones. Análisis de causa raíz: la app accounts tenía modelos pero no tenía archivos de migración, un clásico cuando no se comitean a control de versiones.
Problema 1 Migraciones de Django ausentes
Investigación: comprobar el directorio accounts/migrations mostraba solo el archivo init.py; revisar accounts/models.py revelaba un CustomUser complejo con relaciones. Solución correcta: generar las migraciones en local o en un entorno de desarrollo, revisarlas, comitearlas y desplegar mediante el pipeline CI CD. Pasos: ejecutar manage.py makemigrations y manage.py migrate en desarrollo, revisar dependencias entre apps con manage.py showmigrations, versionar los archivos 0001_initial y sucesivos, y desplegar.
Antipatrones a evitar: no generes migraciones directamente en el servidor de producción; no ignores conflictos de dependencias entre migraciones; no mezcles generación de migraciones entre ramas o entornos diferentes.
Consejo de oro: verifica dependencias de migraciones con manage.py showmigrations y valida el orden de apps cuando hay relaciones entre ellas.
Problema 2 Pesadilla de autenticación SSH
El repo estaba configurado por HTTPS y GitHub retiró la autenticación por contraseña en 2021. Síntomas: git pull pide usuario y falla, y la conexión SSH muestra error de verificación de clave de host.
Solución paso a paso: 1 comprobar llaves SSH existentes con ls -la en la carpeta .ssh; 2 añadir GitHub a known_hosts con ssh-keyscan -t rsa github.com redirigido a known_hosts; 3 probar conexión con ssh -T git@github.com y confirmar el mensaje de autenticación exitosa; 4 cambiar el remoto de HTTPS a SSH con git remote set-url origin git@github.com usuario repo.git y verificar con git remote -v; 5 depurar con ssh -vT git@github.com y validar la huella de la llave con ssh-keygen -lf sobre tu llave pública.
Problema 3 La máquina del tiempo de ECR
El registro ECR servía una imagen antigua que no incluía las correcciones ni las migraciones. En docker-compose, el tag latest apuntaba a una imagen de hace días. Resultado: aunque el código en GitHub estaba arreglado, los contenedores seguían ejecutando una imagen defectuosa.
Estrategia de arreglo: 1 prueba local para demostrar que el código corregido funciona; cambiar temporalmente image por build en docker-compose, ejecutar docker-compose down y luego docker-compose up --build -d; validar que el backend arranca y aplica migraciones. 2 actualizar ECR con la imagen correcta; iniciar sesión en ECR con aws ecr get-login-password canalizado a docker login, etiquetar la imagen local funcional con docker tag hacia el repositorio ECR y hacer docker push. 3 volver a usar la imagen de ECR en docker-compose sustituyendo build por image, reiniciar servicios con docker-compose down y docker-compose up -d, y comprobar que ahora usa la imagen actualizada.
Lección clave: las imágenes Docker son inmutables y los tags no se actualizan solos; hay que construir y empujar una nueva imagen y apuntar explícitamente a ella.
Problema 4 Dependencias faltantes
Error típico en logs: el paquete cryptography es obligatorio para los métodos de autenticación sha256_password o caching_sha2_password en MySQL 8.1 y superiores. El conector de Python requiere cryptography y no estaba en requirements.txt.
Soluciones: opción recomendada añadir cryptography a requirements.txt con una versión estable. Opción temporal mientras llega el despliegue forzar en MySQL el plugin mysql_native_password mediante el comando del contenedor de base de datos en docker-compose. Tras actualizar dependencias, reconstruir la imagen y volver a desplegar.
Implementación completa de la solución
Composición final: base de datos MySQL 8.1 con healthcheck y plugin de autenticación definido; servicio backend dependiendo de la base de datos saludable, exponiendo el puerto 8000 y consumiendo la imagen actualizada en ECR; variables de entorno para host y puerto de base de datos. Pipeline CI CD ajustado para construir y empujar a ECR tras cada merge a la rama de despliegue.
Verificación: docker-compose ps para ver contenedores corriendo; curl a la ruta admin de Django para confirmar respuesta; docker-compose logs backend con tail para inspeccionar errores; manage.py check y manage.py showmigrations para validar el estado del proyecto.
Resultados y aprendizajes
Antes: backend caía al arrancar, faltaban migraciones, fallaba la autenticación SSH, ECR servía imágenes desactualizadas, y había problemas de conexión a base de datos. Después: backend estable, migraciones aplicadas, SSH operativo, ECR actualizado y conexiones a base de datos sólidas.
Conclusiones clave: 1 gestión de migraciones comitea siempre las migraciones; 2 autenticación SSH entiende cuándo usar SSH frente a HTTPS; 3 inmutabilidad de contenedores los tags deben actualizarse y empujarse a ECR; 4 gestión de dependencias mantén requirements.txt al día; 5 estrategia de depuración avanza por capas base de datos, aplicación, contenedor, registro y pipeline.
Referencia de comandos esenciales
Docker y ECR: docker-compose down; docker-compose up -d; docker-compose ps; docker-compose logs nombre_servicio; aws ecr get-login-password canalizado a docker login; docker tag imagen_local tag remota; docker push al repositorio ECR.
Git y SSH: ssh -T git@github.com; ssh-keyscan -t rsa github.com redirigido a known_hosts; git remote set-url origin git@github.com usuario repo.git; git pull origin rama con la estrategia de merge adecuada.
Django: manage.py makemigrations; manage.py migrate; manage.py showmigrations; manage.py check; manage.py createsuperuser cuando sea necesario.
Estrategias de prevención
Para equipos de desarrollo: comitear migraciones inmediatamente al generarlas; mantener un método de autenticación consistente preferiblemente SSH; mantener requirements.txt actualizado; implementar pipelines CI CD que construyan y publiquen imágenes en ECR; documentar el proceso de despliegue. Para DevOps: automatizar builds en ECR al detectar cambios; añadir healthchecks en los servicios; gestionar variables de entorno con seguridad; monitorizar logs de contenedores; definir procedimientos de rollback.
Sobre Q2BSTUDIO
En Q2BSTUDIO somos una empresa de desarrollo de software con foco en aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud AWS y Azure, servicios de inteligencia de negocio, IA para empresas, agentes IA y Power BI. Diseñamos, desplegamos y operamos plataformas modernas en contenedores con Docker y Kubernetes, optimizadas para CI CD y registros como ECR, integrando buenas prácticas de seguridad desde el inicio. Si necesitas modernizar tu backend, migrarlo a contenedores o estabilizar tu pipeline, nuestro equipo puede ayudarte de extremo a extremo.
Explora cómo convertimos tu arquitectura en una plataforma robusta y escalable con nuestros servicios cloud en AWS y Azure, e impulsa la entrega de producto con aplicaciones a medida y software a medida alineadas a tu negocio.
Cierre
Lo que empezó como un simple el backend está roto se convirtió en una sesión integral de depuración que cubrió migraciones de Django, autenticación SSH, contenedores y gestión de imágenes en ECR, métodos de autenticación de MySQL y ajustes en el pipeline CI CD. Lección final: el desarrollo moderno une muchas piezas; entender cómo interactúan y cómo fallan es la clave para resolver rápidamente. Tiempo invertido 6 horas. Problemas resueltos 5. Conocimiento adquirido incalculable. Estado del backend listo para producción.
¿Has vivido un despliegue infernal parecido Contacta con nosotros y llevamos tu plataforma de roto a a prueba de fallos.