Guía completa para depurar y resolver problemas comunes de despliegue de Django en entornos con contenedores
TLDR
Invertí 6 horas depurando un backend de Django roto en producción. Los problemas incluyeron migraciones faltantes, autenticación SSH fallida, desajustes de tipo en la base de datos, dependencias ausentes y una imagen antigua en ECR. Aquí documento la solución de punta a punta con los comandos clave que utilicé.
Escenario desastre
Te asignan arreglar un backend que no arranca. En los logs, Django marca un error de migraciones que hacen referencia a un nodo padre inexistente en otra app. Clásico caso de migraciones no versionadas.
Fase de diagnóstico
Comandos iniciales: docker-compose logs backend, python manage.py showmigrations. Resultado típico: dependencia en una app sin migraciones y directorio de migrations con solo init.py.
Problema 1 Migraciones de Django faltantes
Hallazgos: la app accounts tenía modelos complejos sin archivos de migración. Causa raíz frecuente cuando las migraciones no se comitean al repositorio.
Solución correcta
1 Generar las migraciones en local o entorno de desarrollo. 2 Comitearlas y subirlas a control de versiones. 3 Desplegar mediante la canalización CI CD oficial.
Práctica recomendada
Usa python manage.py showmigrations para revisar dependencias y el orden aplicado antes de migrar. Ejecuta docker-compose exec backend python manage.py migrate en el entorno de despliegue solo con migraciones ya versionadas.
Problema 2 Autenticación SSH con GitHub
El remoto estaba en HTTPS y GitHub eliminó la autenticación por contraseña hace tiempo. Además, el host no estaba en known_hosts.
Pasos para reparar SSH
1 Revisar claves existentes: ls -la ~/.ssh. 2 Añadir GitHub a known_hosts con ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts. 3 Probar la conexión: ssh -T git@github.com. 4 Cambiar el remoto a SSH: git remote set-url origin git@github.com:usuario/repositorio.git y validar con git remote -v.
Comandos de depuración SSH útiles
ssh -vT git@github.com para salida detallada. ssh-keygen -lf ~/.ssh/id_rsa.pub para verificar la huella de la clave.
Problema 3 La cápsula del tiempo de ECR
En ECR había una imagen antigua sin las correcciones. docker-compose estaba tirando de la etiqueta latest, que apuntaba a una build vieja. Recuerda que las imágenes son inmutables y una etiqueta puede seguir atada a una imagen desactualizada.
Estrategia de corrección ECR
Paso 1 Validación local temporal: cambiar a build local en docker-compose, ejecutar docker-compose down y docker-compose up --build -d para comprobar que el backend funciona con las correcciones.
Paso 2 Actualizar ECR: iniciar sesión con aws ecr get-login-password --region region | docker login --username AWS --password-stdin registro. Etiquetar la imagen local con docker tag imagen-local:latest registro/repositorio:latest. Empujar con docker push registro/repositorio:latest.
Paso 3 Volver a imagen de ECR: restaurar la configuración de docker-compose a image registro repositorio latest y subir con docker-compose up -d.
Problema 4 Dependencias ausentes
Error típico: Django marcando que el paquete cryptography es requerido para sha256_password o caching_sha2_password cuando usas MySQL 8.x. Por defecto MySQL 8 usa caching_sha2_password y el conector de Python necesita cryptography.
Opciones de solución
Opción recomendada: añadir cryptography en requirements.txt, por ejemplo cryptography mayor o igual a 3.4.8. Alternativa temporal: iniciar MySQL con el plugin mysql_native_password usando command --default-authentication-plugin=mysql_native_password en el servicio de la base de datos de docker-compose.
Implementación final de la solución
Estructura clave de docker-compose: servicio db con imagen mysql 8.1, healthcheck activado, variables de entorno para base de datos y el plugin de autenticación ajustado si es necesario. Servicio backend con image del ECR actualizada, restart always, mapeo de puerto 8000, depends_on con condición service_healthy y variables de entorno DATABASE_HOST db y DATABASE_PORT 3306.
Verificación
Comprobar contenedores: docker-compose ps. Probar endpoint del backend: curl -s https://localhost:8000/admin/login. Revisar logs: docker-compose logs backend --tail=20.
Resultados
Antes: el backend caía al iniciar, faltaban migraciones, fallaba la autenticación SSH, ECR servía una imagen obsoleta y había problemas de conexión a la base de datos. Después: backend estable, migraciones aplicadas, SSH funcionando, ECR actualizado y conexiones de base de datos estables.
Aprendizajes clave
1 Gestión de migraciones: siempre versiona las migraciones. 2 Autenticación SSH: usa SSH frente a HTTPS cuando sea posible y cuida known_hosts. 3 Inmutabilidad de contenedores: ECR no se actualiza solo, debes construir y empujar nuevas imágenes. 4 Dependencias: mantén requirements.txt al día, especialmente con cambios de motor o método de autenticación. 5 Estrategia de depuración por capas: base de datos, aplicación, contenedor, registro, pipeline.
Referencia esencial de comandos
Docker y ECR: docker-compose down, docker-compose up -d, docker-compose ps, docker-compose logs servicio, aws ecr get-login-password --region region, docker login, docker tag imagen-local:tag registro repositorio:tag, docker push registro repositorio:tag.
Git y SSH: ssh -T git@github.com, ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts, git remote set-url origin git@github.com:usuario/repositorio.git, git pull origin rama --no-rebase.
Django: docker-compose exec backend python manage.py makemigrations, migrate, showmigrations.
Estrategias de prevención para equipos
Desarrollo: comitear migraciones tras generarlas, mantener requirements, documentar el proceso de despliegue, usar pipelines de CI CD que construyan y publiquen imágenes en ECR. DevOps: builds automáticas en ECR ante cambios en main, healthchecks en docker-compose y orquestadores, buena gestión de variables de entorno y secretos, monitoreo de logs, y procedimientos de rollback.
Conclusión
Un ticket de backend roto destapó problemas de migraciones de Django, flujos SSH y Git, contenerización y gestión de imágenes en ECR, métodos de autenticación de MySQL y ajustes en la CI CD. La lección clave: el desarrollo moderno integra múltiples piezas y comprender cómo fallan acelera la resolución.
Tiempo invertido: 6 horas. Problemas resueltos: 5. Estado del backend: listo para producción.
En Q2BSTUDIO somos una empresa de desarrollo de software y aplicaciones a medida, expertos en software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio con power bi, automatización y agentes IA. Si necesitas desplegar Django en AWS, contenerizar servicios o diseñar una arquitectura robusta y observable, podemos ayudarte. Descubre cómo aceleramos tus proyectos con nuestro equipo de plataformas y DevOps en nuestra página de servicios cloud aws y azure, y si buscas integrar tu backend con frontends multiplataforma o crear productos escalables y mantenibles, visita nuestra propuesta de aplicaciones a medida y software a medida. Potenciamos la ia para empresas con agentes IA y analítica con power bi para llevar tus decisiones al siguiente nivel.
¿Has vivido una odisea similar de despliegue Django Docker ECR y SSH con migraciones ausentes Permítenos ayudarte a convertir lo roto en robusto.
