Desplegar Django con Kamal en servidores propios

Tienes un proyecto Django que ya ha dejado atrás la fase de prototipo, con usuarios reales o a punto de tenerlos, y cada nueva versión sigue dependiendo de una secuencia de pasos que solo una persona del equipo domina de principio a fin. Alguien entra por SSH al servidor, hace un pull, reinicia el servicio, comprueba que la web carga y espera que nada se haya roto por el camino.

Ese modelo puede funcionar durante un tiempo. El problema no es que el despliegue manual sea imposible, sino que es difícil de repetir con seguridad. Cuando un paso cambia y no queda documentado, el proceso se vuelve un poco más frágil. Cuando el equipo crece, esa fragilidad acumulada empieza a convertirse en riesgo real: despliegues fallidos, tiempo de inactividad innecesario y la sensación generalizada de que todo se sostiene con alambre.

Kamal aparece como respuesta a ese escenario concreto. No como una plataforma de orquestación, ni como sustituto de la infraestructura que ya tienes, sino como una forma de estandarizar cómo se construye, publica y actualiza tu aplicación en servidores que controlas directamente.

Qué es Kamal y qué problema resuelve al desplegar Django

Kamal es una herramienta de despliegue para aplicaciones empaquetadas en contenedores. No crea infraestructura ni diseña tu arquitectura: introduce un proceso repetible para publicar nuevas versiones en máquinas que ya tienes y administras. Desarrollada por el equipo de 37signals, nació de una necesidad muy concreta: desplegar aplicaciones web en servidores propios sin depender de plataformas gestionadas ni montar un clúster de Kubernetes, porque entre ambos extremos existía un vacío donde la mayoría de equipos pequeños y medianos se movían con scripts artesanales que funcionaban hasta que dejaban de hacerlo.

El valor real de Kamal está en la disciplina operativa que introduce en el ciclo de despliegue: construir la imagen, publicarla en un registro, desplegarla en los servidores de destino y coordinar los servicios relacionados con un flujo predecible que se repite de la misma manera en cada nueva versión sin necesidad de recordar pasos manuales intermedios.

Para proyectos Django desplegados en servidores propios o VPS, este encaje resulta especialmente natural porque la mayoría de aplicaciones Django comparten una arquitectura reconocible: un servicio web que atiende peticiones HTTP, uno o varios workers que procesan tareas asíncronas en segundo plano, una base de datos PostgreSQL, una capa de caché con Redis y un proxy de entrada que gestiona el tráfico público. Kamal sabe coordinar todas esas piezas sin obligarte a adoptar una plataforma mucho más grande de la que realmente necesitas, lo que lo convierte en una opción muy razonable para ese punto intermedio donde los scripts manuales ya no dan confianza suficiente pero Kubernetes representaría un salto de complejidad desproporcionado.

Lo que Kamal no es. Conviene dejarlo claro desde el principio para evitar expectativas erróneas: Kamal no sustituye a Docker, ni al proxy inverso, ni a PostgreSQL, ni a tu proveedor de infraestructura. No diseña la arquitectura de tu aplicación, no convierte una aplicación mal preparada para producción en una aplicación robusta y no elimina la necesidad de tomar decisiones sobre backups, seguridad, observabilidad o persistencia de datos. Presentarlo como "tu propia PaaS" sería engañoso porque en realidad es una herramienta de despliegue y coordinación de contenedores, no una plataforma completa que cubra todo el ciclo operativo de una aplicación en producción.

Cuándo tiene sentido usar Kamal para desplegar Django

No todos los proyectos necesitan Kamal, y reconocer si el tuyo encaja antes de invertir tiempo en configurarlo te puede ahorrar bastantes problemas a medio plazo. El criterio de fondo es relativamente simple: Kamal resulta útil cuando quieres estandarizar tus despliegues sin asumir la complejidad de una plataforma de orquestación mayor, y encaja peor cuando tu sistema ya ha crecido hasta un punto en que necesita capacidades que van más allá de coordinar contenedores sobre servidores conocidos.

Donde encaja

El perfil más habitual es el de equipos pequeños o medianos que mantienen control sobre sus servidores —por coste, simplicidad operativa o preferencia por una infraestructura comprensible— y trabajan en proyectos con arquitectura moderada: una aplicación Django como servicio principal, uno o varios workers, base de datos y cache. Encaja especialmente bien en productos con un ritmo de cambios regular, donde importa desplegar de manera ordenada y con confianza, sin necesidad de cambiar de proveedor, migrar a una plataforma gestionada ni montar infraestructura adicional que después hay que mantener.

Donde encaja peor

Sus límites aparecen en sistemas con arquitecturas complejas: muchos servicios independientes, escalado desigual, necesidades avanzadas de red, despliegues multirregión o requisitos estrictos de aislamiento entre servicios. También encaja peor en organizaciones que ya dependen de una plataforma gestionada y no quieren asumir la operación directa de servidores.

Y conviene decirlo con claridad: si en tu equipo nadie puede o quiere ocuparse de operar servidores —seguridad, backups, recuperación ante fallos, actualizaciones del sistema y mantenimiento general—, Kamal no resuelve ese problema. Simplifica el despliegue, pero no externaliza la responsabilidad de producción. En esos casos, una plataforma gestionada puede tener más sentido.

"Arquitectura simple" no significa proyecto pequeño ni poco serio, sino que el modelo de "contenedor más servidor más despliegue coordinado" sigue siendo suficiente para representar tu sistema real.

Las piezas necesarias antes de tocar la configuración

Antes de abrir ningún fichero de configuración de Kamal, conviene tener claro qué piezas componen tu sistema, qué responsabilidad tiene cada una y qué relaciones existen entre ellas. Saltarse este paso es una causa frecuente de despliegues que parecen funcionar al principio pero se rompen tras el primer reinicio o redeploy.

La aplicación Django es el centro del sistema porque sirve las peticiones web, concentra la lógica de negocio y depende de configuración, secretos y servicios externos para funcionar correctamente, pero no es la única pieza que necesita atención durante el despliegue ni la más difícil de gestionar.

El proxy de entrada recibe el tráfico que llega al dominio público, termina la conexión TLS si corresponde y reenvía las peticiones al servicio web de la aplicación. Kamal puede gestionar esta capa pero necesita que el dominio, el DNS y la configuración de red ya estén correctamente planteados antes de que el despliegue los requiera, porque la capa de acceso público no aparece por arte de magia solo por usar una herramienta de despliegue.

Los workers procesan tareas asíncronas cuando el proyecto utiliza colas de trabajo, ya sea con Celery, Django-RQ u otra solución similar. Es importante entender que los workers son procesos completamente distintos del servicio web aunque suelan compartir la misma imagen de contenedor y la misma base de código: tienen su propio perfil de consumo de recursos, su propio ritmo de ejecución y sus propias necesidades de configuración. Si tu aplicación procesa pagos en segundo plano, envía correos electrónicos, genera informes o ejecuta cualquier tipo de tarea diferida, los workers no son un complemento opcional sino una parte esencial del despliegue, y publicar solo la parte web asumiendo que lo asíncrono "ya funcionará" es una fuente de incidentes mucho más frecuente de lo que parece.

La base de datos tiene su propio ciclo de vida, su propia estrategia de backups y sus propias necesidades de persistencia y recuperación que no deberían tratarse como un detalle más dentro del contenedor de la aplicación. Lo mismo aplica a la caché: Redis aparece con frecuencia en proyectos Django para gestionar colas, sesiones, bloqueos distribuidos o simplemente para mejorar el rendimiento de consultas repetidas, y en todos los casos necesita una decisión deliberada y consciente sobre dónde se ejecuta, cómo se persisten los datos si es necesario y qué ocurre cuando el servicio se reinicia.

Los ficheros persistentes —media uploads subidos por usuarios, activos generados por la aplicación o cualquier contenido que deba sobrevivir al ciclo de vida del contenedor— merecen atención especial porque si el contenedor se reemplaza en cada despliegue (que es exactamente lo que ocurre cuando usas Kamal), cualquier fichero almacenado dentro de él desaparece con la versión anterior sin posibilidad de recuperación.

La relación entre todas estas piezas también importa para el despliegue. El servicio web atiende tráfico y consulta la base de datos y la caché según la lógica de la aplicación; los workers consumen tareas desde la cola y generalmente dependen de la misma configuración base que la parte web; la base de datos y la caché son dependencias de infraestructura con ciclos de vida propios, no componentes efímeros que aparecen y desaparecen con cada release; y el proxy expone una interfaz pública estable aunque la versión interna de la aplicación cambie con cada despliegue.

La distinción fundamental es esta: Kamal despliega y coordina contenedores de aplicación, pero no resuelve por sí mismo el diseño de la base de datos, los backups, la persistencia, la estrategia de medias y ficheros ni la seguridad de red. Confundir herramienta de despliegue con arquitectura de producción es uno de los errores más habituales.

Preparar la aplicación antes del primer despliegue

El despliegue correcto empieza mucho antes del primer comando, y la mayoría de tutoriales y guías rápidas cometen el error de saltar directamente a la configuración de Kamal dejando implícito todo el trabajo de preparación previo, que es precisamente donde se concentran los errores más difíciles de diagnosticar en producción porque no aparecen de forma obvia ni generan mensajes de error claros.

La aplicación Django debe estar preparada para producción. No basta con que el Dockerfile arranque. Necesitas configuración separada del entorno local, ALLOWED_HOSTS correcto, DEBUG desactivado, HTTPS y cookies seguras, estrategia clara para collectstatic, logging útil y algún health check que confirme que la aplicación funciona de verdad. Si tu proyecto usa Wagtail, la gestión de media files cobra todavía más importancia.

La imagen Docker debe poder construirse de forma consistente y reproducible. Eso significa un Dockerfile entendible donde cada instrucción tenga una razón de ser, dependencias del sistema claramente definidas, un proceso de build que no dependa de pasos manuales ocultos ni de configuraciones locales del desarrollador, y comandos de arranque bien diferenciados tanto para la parte web (Gunicorn u otro servidor WSGI) como para los workers. Sin una imagen reproducible que puedas construir de forma idéntica en cualquier momento y en cualquier máquina, Kamal solo conseguiría automatizar la fragilidad en lugar de eliminarla.

Las variables de entorno y los secretos deben estar definidos antes del primer despliegue. La SECRET_KEY, las credenciales de la base de datos y las claves de servicios externos no deben ir dentro de la imagen ni quedar expuestas en el repositorio. En Kamal, lo habitual es gestionarlos a través de .kamal/secrets o integraciones con gestores externos, y cargar esos valores en el despliegue o en tiempo de ejecución. Aun así, sigue siendo responsabilidad del equipo decidir quién accede a ellos, cómo se rotan y qué ocurre cuando cambian.

Antes de escribir la configuración de Kamal conviene cerrar algunas decisiones clave. Dónde vivirán PostgreSQL y Redis, cómo resolver la persistencia de ficheros, cómo se ejecutarán las migraciones y si web y workers compartirán la misma imagen. Son decisiones fáciles de posponer porque no impiden que el primer despliegue arranque, pero acaban apareciendo como problemas en producción.

Las dependencias externas también deben estar listas. Un registro de contenedores accesible donde publicar las imágenes (Docker Hub, GitHub Container Registry o un registro privado como AWS ECR), acceso SSH al servidor de destino con credenciales correctamente configuradas, certificados TLS y dominio resueltos y apuntando al lugar correcto, y conectividad validada entre el servidor y todos los servicios auxiliares que la aplicación necesita. Si la aplicación depende de proveedores externos para el envío de correo, el almacenamiento de ficheros, APIs de terceros o sistemas de colas externas, su configuración y accesibilidad también condicionan que el despliegue realmente funcione.

Lo que suele olvidarse en esta fase es separar bien static files y media files, dar a workers y tareas programadas su propia configuración y revisar permisos, timeouts y el ciclo de vida de los contenedores. Sin una preparación completa Kamal solo automatiza un sistema frágil, por lo que es necesario concentrarse en disponer de todo lo necesario antes de iniciar la configuración de Kamal.

Traducir la arquitectura Django a la configuración de Kamal

Una vez que las piezas del sistema están claras y las decisiones previas están tomadas, el siguiente paso consiste en modelar esa arquitectura en la configuración de Kamal, y esta traducción resulta ser uno de los ejercicios más reveladores de todo el proceso porque te obliga a hacer explícito lo que en otros enfoques de despliegue suele quedar implícito, disperso entre scripts o simplemente asumido por la persona que "sabe cómo funciona todo".

Roles y servidores. En Kamal lo habitual es separar al menos un rol web y un rol worker. El rol web ejecuta Django con Gunicorn u otro servidor WSGI para responder a peticiones HTTP. El rol worker ejecuta Celery, Django-RQ o la cola que use el proyecto para tareas asíncronas. Una sola imagen de contenedor puede servir para ambos roles cambiando únicamente el comando de arranque, lo que simplifica las releases porque solo hay una imagen que construir y distribuir, pero exige que esos comandos estén bien definidos, documentados y probados de forma independiente.

Cuándo todo cabe en un host y cuándo deja de ser razonable. Para un primer despliegue, o para una aplicación Django con tráfico moderado, puede ser razonable empezar con web y workers en un solo servidor. Cuando el tráfico crece o Celery empieza a competir con Gunicorn por CPU y memoria, separar roles en distintos hosts deja de ser una mejora opcional y pasa a ser una necesidad. El momento de pensar en esa separación es ahora —durante la configuración inicial— aunque la implementes más adelante, porque tener los roles bien definidos desde el principio hace que la migración posterior sea un cambio de configuración en lugar de una reestructuración del despliegue entero.

Imagen y build. La imagen debe contener todo lo necesario para ejecutar la aplicación de forma reproducible: el código, las dependencias (Python y de sistema) y comandos de arranque bien definidos. También es importante que ni los secretos ni la configuración sensible queden incrustados en la imagen, sino que se inyecten en tiempo de ejecución de forma independiente.

Variables, secretos y configuración. En Kamal, la configuración normal y los secretos se gestionan por separado. Las variables de entorno no sensibles pueden declararse directamente en la configuración del despliegue, mientras que los secretos se guardan cifrados y Kamal los inyecta en los contenedores en tiempo de ejecución. Esto permite definir de forma clara qué valores necesita la aplicación Django para arrancar, qué comparten la parte web y los workers, y qué datos sensibles deben mantenerse fuera de la imagen. En la práctica, Kamal actúa como punto de unión entre la configuración del despliegue y las credenciales que necesita la aplicación en producción.

Proxy, dominio y TLS. Kamal gestiona la entrada pública del tráfico con kamal-proxy, que se encarga de publicar la aplicación y enrutar las peticiones hacia el contenedor correcto. Aun así, para que funcione bien necesitas tener preparado el dominio, el DNS y la red del servidor. Si vas a usar HTTPS automático, Kamal puede obtener certificados con Let’s Encrypt cuando despliegas sobre un solo servidor y el dominio apunta correctamente a esa máquina. También conviene revisar opciones como app_port, host, ssl, forward_headers y el healthcheck, porque forman parte de cómo Kamal expone y valida la aplicación en producción.

Volúmenes y persistencia. Si tu aplicación Django guarda media files, uploads u otros datos persistentes, no pueden vivir dentro del contenedor, porque se reemplaza en cada despliegue. Kamal permite declararlos en la configuración mediante volumes, montando rutas del host dentro del contenedor para que sobrevivan entre releases. La alternativa es resolverlo con almacenamiento externo. En ambos casos, la idea es la misma: sacar los datos persistentes del ciclo de vida efímero de la imagen.

Servicios auxiliares. No todas las piezas del sistema tienen por qué vivir dentro del mismo despliegue de Kamal. Decidir qué queda dentro y qué queda fuera es una parte importante del diseño operativo. PostgreSQL y Redis pueden gestionarse como accesorios de Kamal o mantenerse fuera, pero conviene tomar esa decisión de forma explícita. En muchos proyectos, una opción razonable es dejar PostgreSQL como servicio externo —porque tiene su propio ciclo de vida, backups y mantenimiento— y usar Redis como accesorio ligado al despliegue de la aplicación, ya que su ciclo suele estar más cerca del código y de los workers.

Particularidades de Django dentro del modelo de despliegue

Django no es solo un contenedor web que arranca y responde peticiones. Para desplegar Django con Kamal de forma fiable hay que tener en cuenta algunas piezas que forman parte del propio ciclo de release.

collectstatic debe formar parte del despliegue. Django necesita recopilar los static files antes de servir la aplicación, así que collectstatic debe tener un lugar claro en la secuencia de release, normalmente como hook. Además, conviene decidir de antemano cómo se van a servir esos assets, ya sea con WhiteNoise, un proxy dedicado o un CDN, porque esa decisión afecta al Dockerfile, al proxy y a la validación posterior. Si collectstatic falla, la aplicación puede arrancar y aun así renderizar de manera incorrecta.

Las migraciones necesitan una estrategia concreta. Las migraciones simples suelen encajar bien dentro del flujo normal de despliegue. El problema aparece con cambios grandes o destructivos: tablas con mucho volumen, columnas que desaparecen o cambios incompatibles con el código anterior. En esos casos conviene desplegar por fases y mantener compatibilidad temporal entre código y esquema, porque hacer rollback del código no deshace automáticamente la migración de la base de datos. Si la migración ya se aplicó y necesitas volver a la versión anterior porque algo ha fallado, la base de datos no retrocede automáticamente al estado previo, y forzar una migración inversa en caliente es una operación arriesgada que puede provocar pérdida de datos.

Web y workers comparten código, pero no el mismo contexto. En proyectos con Celery o Django-RQ, los workers pueden seguir procesando tareas añadidas a la cola por una versión anterior del código mientras la parte web ya corre una nueva release. Si cambias una tarea o el formato de los datos que espera, se puede romper el procesamiento asíncrono sin tocar la parte web. Por eso conviene tratar la compatibilidad de tareas con el mismo cuidado que las migraciones.

Tareas programadas. Si tu aplicación ejecuta tareas a intervalos regulares —como envío de emails programados, limpieza de datos temporales, generación de informes o sincronización con servicios externos—, hay que decidir dónde y cómo se ejecutan dentro del modelo de despliegue. Pueden vivir en un proceso dedicado gestionado por Kamal, delegarse a una herramienta externa como un cron del sistema operativo del host, o ejecutarse dentro de los workers existentes mediante un planificador como Celery Beat. Cada opción tiene sus implicaciones en cuanto a fiabilidad, visibilidad y facilidad de depuración, y lo importante es que la decisión sea consciente en lugar de dejarla al azar o a la costumbre heredada de la fase de desarrollo.

En conjunto, collectstatic, las migraciones, los workers y las tareas programadas no son detalles secundarios. Forman parte del despliegue real de Django y conviene tratarlos como tal desde el principio, porque cuando el proyecto crezca esa separación conceptual será la base sobre la que se apoye cualquier evolución de la arquitectura.

Preparar los servidores y el entorno base

Antes del primer despliegue, el servidor tiene que estar listo para ejecutar la aplicación de forma estable y segura. Eso incluye acceso SSH con claves, un usuario de despliegue con permisos mínimos, Docker funcionando correctamente y recursos suficientes para la parte web, los workers y los servicios auxiliares.

También conviene verificar la conectividad con el registro de imágenes y con las dependencias externas de la aplicación, como PostgreSQL, Redis o APIs de terceros. Si esa conectividad falla, el problema no está en Kamal, sino en el entorno.

La red debe estar definida con intención. Solo deberían exponerse los puertos necesarios, normalmente 80 y 443, y el resto debería quedar bloqueado por firewall o por reglas de red del proveedor. En un VPS esto puede resolverse con ufw o iptables; en AWS, con security groups. Es una preparación básica, pero marca la diferencia entre un entorno listo para producción y uno que solo parece estarlo.

El primer despliegue y lo que suele descubrir

El primer despliegue es el momento en que toda la configuración deja de ser teórica y se enfrenta a la realidad del servidor, la red y las dependencias. Aunque todo parezca listo, es normal que aquí aparezcan supuestos falsos que en local no se veían.

La secuencia con Kamal es sencilla y predecible. Se construye la imagen desde el Dockerfile, se publica en el registro, Kamal conecta por SSH, descarga la imagen, arranca los contenedores según los roles definidos y ejecuta los hooks de release, como collectstatic o las migraciones. Esa repetibilidad es precisamente una de sus ventajas: el despliegue deja de depender de pasos manuales o de la memoria de una sola persona.

Lo que más suele fallar la primera vez son variables de entorno que faltan, errores de conectividad con PostgreSQL o Redis, dependencias del sistema que no estaban realmente en la imagen, permisos incorrectos en media files o logs, y problemas con static files que solo aparecen al acceder por el dominio real. No son errores extraños: son parte normal de validar el entorno.

Ninguno de estos problemas es grave si lo esperas y lo diagnosticas con calma. La primera ejecución no es realmente un lanzamiento a producción sino un ejercicio de validación que te permite confirmar que todas las piezas encajan correctamente, y tratarla como tal reduce la frustración y permite resolver los problemas de forma ordenada. El objetivo no es que todo funcione a la primera sino que cuando algo falle sepas exactamente dónde mirar para resolverlo.

Despliegues sucesivos, migraciones y vuelta atrás

El valor real de Kamal aparece a partir del segundo despliegue. Cada nueva release sigue el mismo flujo: construir la imagen, publicarla, desplegarla y ejecutar los hooks definidos. Esa repetibilidad permite desplegar con más frecuencia y con menos incertidumbre, porque el proceso deja de depender de pasos manuales. Los despliegues frecuentes con cambios incrementales reducen de forma significativa la tasa de fallos en producción porque cada release individual es más fácil de entender, de verificar y de revertir si algo no funciona como se esperaba.

Las migraciones siguen siendo la parte más sensible. Las migraciones simples suelen encajar bien en el flujo normal de release. En cambio, los cambios destructivos o que afectan a mucho volumen de datos conviene tratarlos aparte y por fases, manteniendo compatibilidad temporal entre el código y el esquema de la base de datos. El motivo es simple: un rollback de la aplicación no revierte automáticamente la migración. Requiere más trabajo de planificación, pero evita el escenario en que un despliegue fallido deja la base de datos en un estado inconsistente.

El rollback es útil, pero no mágico. Kamal permite volver rápido a una release anterior del código, pero eso no deshace cambios en datos, tareas ya procesadas o migraciones aplicadas. Por eso la estrategia de rollback debe pensarse antes del problema, no durante el incidente. Un despliegue sin tiempo de inactividad bien diseñado incluye la capacidad de retroceder como parte del plan normal, no como un recurso de emergencia que se improvisa cuando todo lo demás ha fallado.

Validaciones después de desplegar

Hay una diferencia importante entre "la release ha arrancado" y "la aplicación está realmente desplegada y funcionando correctamente", y dar por bueno un despliegue solo porque los contenedores están levantados es un error que suele pagarse con incidentes detectados por los usuarios en lugar de por el equipo. Verificar que todo funciona como se espera después de cada despliegue es tan importante como el despliegue en sí, y conviene que esas verificaciones estén definidas de antemano para no depender de la improvisación ni del recuerdo individual.

Lo mínimo que conviene validar después de cada despliegue es que la aplicación responde desde el dominio correcto, que PostgreSQL y Redis están accesibles, que los static files y media files siguen sirviéndose bien, que al menos un flujo funcional básico —como el login— funciona sin errores y que los workers procesan tareas si existen procesos asíncronos. También merece la pena revisar los logs de arranque para detectar errores repetitivos o fallos silenciosos.

Si tu equipo ya tiene monitorización en producción configurada, estas validaciones se integran naturalmente con las alertas existentes y pueden automatizarse en gran medida. Si todavía no la tienes, este es un buen momento para planteártela, porque cada despliegue es un punto de riesgo que la monitorización convierte en un punto de control observable y medible.

El despliegue como consecuencia, no como objetivo

Kamal encaja muy bien para desplegar Django de forma estandarizada en servidores propios, y resulta especialmente útil para equipos pequeños y medianos que necesitan un proceso de despliegue repetible, predecible y documentado sin asumir la complejidad de Kubernetes o de una plataforma de orquestación mayor. Su valor no está en resolver la producción entera sino en simplificar una parte concreta y crítica —el acto de desplegar— y hacerla lo suficientemente fiable como para que deje de ser una fuente de estrés.

Para que eso funcione, la aplicación también tiene que estar bien planteada: arquitectura clara, secretos bien gestionados, persistencia resuelta, migraciones compatibles y validaciones después de cada release. Si esas piezas faltan, Kamal no corrige el problema, solo acelera un proceso que sigue siendo frágil.

Por eso su mejor encaje suele estar en ese punto intermedio donde los scripts manuales ya no bastan, pero una orquestación compleja todavía no compensa el coste de adoptarla y mantenerla. En muchas aplicaciones Django, este momento llega antes de lo que parece. Reconocerlo a tiempo es lo que separa a los equipos que despliegan con confianza de los que siguen cruzando los dedos después de cada push.