Para este workshop vamos a necesitar:

• uv (para instalar Python y las dependencias del proyecto)
• AWS CLI (para conectarnos con Amazon Web Services)
• GitHub CLI (gh) (para gestionar nuestros repositorios)

Además, usaremos nginx, Docker y Terraform, aunque no será necesario instalarlos localmente.

Abre tu terminal (PowerShell o CMD en Windows, Terminal en Mac/Linux) y verifica qué tienes ya instalado:

# Verifica si tienes uv
uv --version

# Verifica si tienes AWS CLI
aws --version

# Verifica si tienes GitHub CLI
gh --version

Vamos a crear un proyecto base de Django desde cero. Servirá para entender la estructura y preparar el entorno.

1. Crear la carpeta del proyecto:

mkdir proyecto1 && cd proyecto1
uv init --bare

Esto crea un pyproject.toml, el archivo que describe el proyecto y sus dependencias. Cada proyecto en su propio directorio evita mezclar archivos.

2. Instalar las dependencias básicas:

uv add django gunicorn psycopg2-binary

uv crea el entorno virtual .venv y guarda las versiones exactas en uv.lock:

• django: framework principal
• gunicorn: servidor de producción
• psycopg2-binary: conector para PostgreSQL

Así desarrollo y producción usan la misma base.

Ejecutamos el servidor de desarrollo. No se usa en producción, pero permite probar la aplicación localmente:

uv run python manage.py runserver

Prueba en el navegador: http://127.0.0.1:8000/. Si aparece la página de inicio de Django, el entorno está listo.

Sube pyproject.toml y uv.lock al repositorio: con ellos, uv sync instala las mismas versiones en cualquier máquina.

Sin Docker:

• Configurar manualmente cada servidor
• Instalar dependencias (Python, nginx, etc.)
• Ajustar según el sistema operativo
• Inconsistencias entre entornos
• "Funciona en mi máquina, pero no en producción"

Con Docker:

• Empaquetas la app junto con sus dependencias
• La misma imagen funciona en cualquier entorno
• Despliegues consistentes
• Aislamiento entre aplicaciones

FROM python:3.14-slim
COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /bin/

# Puerto de la aplicación y entorno virtual que crea uv
ENV PORT=8080
ENV PATH="/app/.venv/bin:$PATH"

# Carpeta de trabajo dentro del contenedor
WORKDIR /app

# Instalar las versiones exactas de uv.lock
COPY pyproject.toml uv.lock /app/
RUN uv sync --locked --no-dev

# Copiar el proyecto
COPY . /app

EXPOSE ${PORT}
CMD ["gunicorn", "proyecto1.wsgi:application", "--bind", "0.0.0.0:8080"]

Cada línea es una capa. Docker cachea cada capa para acelerar los siguientes builds.

Crea también un archivo .dockerignore con la línea .venv, para que COPY . /app no copie tu entorno local encima del que instaló uv.

Build time (docker build):

• Se ejecutan: FROM, WORKDIR, COPY, RUN, ENV
• Resultado: una imagen inmutable
• Se ejecuta una vez (o cuando cambias el Dockerfile)
• Usa la caché de capas para acelerar

Runtime (docker run):

• Se ejecuta: CMD
• Resultado: un contenedor en ejecución
• Cada docker run crea un contenedor nuevo
• El contenedor se detiene cuando termina el proceso de CMD

Con el Dockerfile listo, construye la imagen:

docker build -t proyecto1-ec2:latest .

Y ejecuta el contenedor:

docker run -d -p 8000:8080 proyecto1-ec2:latest

Esto enlaza el puerto 8080 del contenedor con el puerto 8000 de tu máquina: la aplicación queda en http://localhost:8000.

Para detener el contenedor:

docker ps
docker kill <container_id>

Manual (desventajas):

• No es repetible
• No tiene historial de cambios
• Es difícil de compartir con el equipo
• No se revisa en code review

Con código (recomendado):

• Es repetible
• Se versiona con git
• Se revisa en code review
• El código sirve como documentación

Nuestro objetivo final es:

1. Migrar Django de la ejecución local a un contenedor Docker (algunos lo llaman dockerizar)
2. Crear la imagen Docker y subirla a AWS ECR (Elastic Container Registry)
3. Usar Terraform para crear un servidor EC2 que descargue y ejecute tu imagen (lo veremos en esta sección)
4. Abrir tu aplicación desde el navegador en una IP pública

[1] VPC (Virtual Private Cloud): tu terreno delimitado en AWS. Todo vive aquí dentro.

[2] Subnets: zonas dentro de la VPC para organizar recursos.

[3] Internet Gateway: la puerta que conecta tu edificio con internet.

[4] Route Tables: definen las rutas del tráfico dentro de la red.

[5] Security Groups: guardias que controlan quién entra y por dónde.

[6] EC2 Instance: el servidor donde corre tu aplicación; en este caso, Django.

Primero, indicamos a Terraform que usaremos AWS como proveedor:

provider "aws" {
  region = "us-east-2"
}

resource "aws_vpc" "default" {
  cidr_block = "10.0.0.0/16"
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = { Name = "Django_VPC" }
}

El segundo bloque define nuestra red privada (VPC).

enable_dns_support activa la resolución de nombres dentro de la VPC.

enable_dns_hostnames asigna nombres DNS internos a las instancias, de modo que podamos usar nombres como db.internal en lugar de direcciones IP (mucho más fácil de recordar).

El Internet Gateway da a los recursos de la VPC acceso a internet (por ejemplo, para actualizar paquetes o exponer una app web):

resource "aws_internet_gateway" "default" {
  vpc_id = aws_vpc.default.id

  tags = {
    Name = "Django_IGW"
  }
}

Ojito a aws_vpc.default.id. Terraform entiende las dependencias: no puedes crear el gateway sin la VPC primero.

resource "aws_subnet" "public_a" {
  vpc_id                  = aws_vpc.main.id
  cidr_block              = "10.0.1.0/24"
  availability_zone       = "${var.aws_region}a"
  map_public_ip_on_launch = true

  tags = {
    Name = "Subnet-Public-A"
  }
}

resource "aws_subnet" "public_b" {
  vpc_id                  = aws_vpc.main.id
  cidr_block              = "10.0.2.0/24"
  availability_zone       = "${var.aws_region}b"
  map_public_ip_on_launch = true

  tags = {
    Name = "Subnet-Public-B"
  }
}

La tabla de rutas da salida a internet a ambas subnets públicas:

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.main.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.gw.id
  }

  tags = { Name = "RT-Public-Django" }
}

Traducción: "si el destino NO está dentro de la VPC (10.0.0.0/16), envíalo a internet por el Internet Gateway".

# Asociar la subnet A con la tabla de rutas
resource "aws_route_table_association" "a" {
  subnet_id      = aws_subnet.public_a.id
  route_table_id = aws_route_table.public.id
}

# Asociar la subnet B con la tabla de rutas
resource "aws_route_table_association" "b" {
  subnet_id      = aws_subnet.public_b.id
  route_table_id = aws_route_table.public.id
}

Un grupo de seguridad define qué tráfico entra a nuestras instancias EC2 dentro de la VPC:

resource "aws_security_group" "ec2_sg" {
  vpc_id = aws_vpc.default.id

  # Permitir tráfico HTTP desde cualquier lugar
  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

También se puede añadir una regla que permita conectarnos a la instancia por SSH desde nuestra IP pública.

Las reglas de salida (egress) controlan el tráfico desde nuestras instancias hacia otros destinos, como internet:

resource "aws_security_group" "ec2_sg" {
  vpc_id = aws_vpc.default.id

  egress {
    from_port   = 0
    to_port     = 65535
    protocol    = "-1"              # Todos los protocolos
    cidr_blocks = ["0.0.0.0/0"]     # Cualquier destino en la red
  }
}

Aquí ingress y egress aparecen por separado para mayor claridad. En la práctica, ambas reglas se definen dentro del mismo recurso.

Nuestra instancia EC2 necesita permisos para descargar imágenes Docker desde ECR. Para ello creamos un rol IAM (aws_iam_role) que la instancia puede asumir.

El rol otorga credenciales temporales con los permisos necesarios.

resource "aws_iam_role" "ec2_ecr" {
  name = "ec2_ecr_access"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Action = "sts:AssumeRole"
      Effect = "Allow"
      Principal = { Service = "ec2.amazonaws.com" }
    }]
  })
}

Finalmente, creamos la instancia EC2 donde se ejecutará nuestra aplicación Django:

resource "aws_instance" "django_server" {
  ami                         = "ami-0c101f26f147fa7fd"
  instance_type               = "t3.micro"
  subnet_id                   = aws_subnet.public_a.id
  vpc_security_group_ids      = [aws_security_group.ec2_sg.id]
  iam_instance_profile        = aws_iam_instance_profile.ec2_profile.name
  associate_public_ip_address = true

  user_data = <<-EOF
    # Aquí va el script que se ejecuta al iniciar la instancia
  EOF

  tags = { Name = "Servidor-Django-Andres" }
}

La instancia usa el rol IAM configurado para obtener acceso de solo lectura a ECR.

Tarde o temprano, Terraform necesita credenciales sensibles (secrets): contraseñas de base de datos, tokens de API o claves de acceso a AWS.

Escribirlas directamente en el código es una mala práctica.

Esto es inseguro: las credenciales quedan expuestas en el código, en terraform.tfstate y quizá en el historial de Git. Aunque el repositorio sea privado, una filtración o un acceso local comprometería toda la infraestructura.

resource "aws_db_instance" "mydb" {
    engine         = "postgres"
    instance_class = "db.t3.micro"

    # 🚨 atención aquí:
    username       = "root"
    password       = "password123"
}

Terraform permite marcar variables como sensitive, para que sus valores no aparezcan en logs ni en la salida de los comandos.

variable "username" {
  type        = string
  sensitive   = true
}

variable "password" {
  type        = string
  sensitive   = true
}

En lugar de valores literales, el recurso usa las referencias var.username y var.password:

username = var.username
password = var.password

Terraform detecta automáticamente las variables de entorno con el prefijo TF_VAR_:

export TF_VAR_username="admin"
export TF_VAR_password="password123"
terraform apply

En Windows (PowerShell):

$env:TF_VAR_username = "admin"
$env:TF_VAR_password = "password123"

Al ejecutar terraform apply, Terraform lee TF_VAR_username y TF_VAR_password y usa sus valores.

Así los valores no están en el código, pero tampoco es del todo seguro: quedan registrados en el historial de la terminal y visibles para otros procesos de tu ordenador.

Otra práctica habitual es un archivo terraform.tfvars con las variables reales:

username = "admin"
password = "password123"

Este archivo no debe subirse al repositorio, así que lo agregamos al .gitignore:

terraform.tfvars
*.tfstate
*.tfstate.backup

Es simple y práctico para entornos locales o de desarrollo.

Pero en un equipo, cada miembro gestiona su propio archivo y debe mantenerlo fuera del control de versiones. Y no soluciona el problema anterior: un proceso malicioso en tu ordenador podría leer tus secretos.

Asigna un nombre para identificar tu clave. En este ejemplo, "key-aws".

En los permisos, selecciona el mismo usuario que creamos en la sección de AWS CLI.

Crea un archivo con las credenciales sensibles, en este caso db-creds.yml:

username: root
password: password123

Cífralo con AWS CLI y la clave KMS:

aws kms encrypt \
      --key-id <KEY_ID> \
      --region us-east-2 \
      --plaintext fileb://db-creds.yml \
      --output text \
      --query CiphertextBlob > db-creds.yml.enc

Reemplaza <KEY_ID> con el ID de tu clave. Si tu archivo YAML tiene otro nombre, cámbialo también en el comando.

El comando genera el archivo cifrado db-creds.yml.enc. Puedes compartirlo de forma segura e incluso incluirlo en los repositorios internos de tu empresa (¿recuerdas que añadimos archivos al .gitignore?).

Terraform descifra las credenciales durante terraform apply:

data "aws_kms_secrets" "creds" {
  secret {
    name    = "db"
    payload = file("${path.module}/db-creds.yml.enc")
  }
}
locals {
  db_creds = jsondecode(
    data.aws_kms_secrets.creds.secret[0].plaintext
  )
}

Ahora el recurso de la base de datos usa las credenciales descifradas:

resource "aws_example_instance" "mydb" {
  engine = "postgres"
  instance_class = "db.t3.micro"
  # Credenciales seguras mediante KMS:
  username = local.db_creds.username
  password = local.db_creds.password
}

AWS Secrets Manager es una alternativa completamente gestionada. Los secretos se guardan cifrados, pueden rotarse automáticamente y Terraform los lee como datos:

data "aws_secretsmanager_secret_version" "creds" {
  secret_id = "db-creds"
}
locals {
  db_creds = jsondecode(
    data.aws_secretsmanager_secret_version.creds.secret_string
  )
}

Crea un secreto nuevo en la consola de AWS, buscando "Secrets Manager", o desde aquí.

Como tipo de secreto, escoge "Other type of secret" y escribe:

{
  "username": "root",
  "password": "password123"
}

Inicializa el directorio y descarga los providers de AWS (solo la primera vez):

terraform init

Revisa los cambios que se aplicarán, sin ejecutarlos todavía:

terraform plan

Aplica los cambios y despliega la infraestructura:

terraform apply

Después de terraform apply, queremos saber la IP de nuestra app:

output "instance_ip" {
  description = "IP pública del servidor Django"
  value       = aws_instance.django.public_ip
}

output "app_url" {
  description = "URL de la aplicación"
  value       = "http://${aws_instance.django.public_ip}"
}

Resultado en terminal:

Outputs:

instance_ip = "99.999.99.999"
app_url     = "http://99.999.99.999"

Copia la URL y ábrela en tu navegador.

Hasta ahora, Django ha usado SQLite, una base de datos en un solo archivo. Sirve para desarrollo, pero no para producción:

• No soporta alta concurrencia (varios usuarios a la vez).
• El archivo vive dentro del contenedor, así que se pierde si el contenedor se reinicia o se reemplaza.

La solución es un servicio de base de datos gestionado como Amazon RDS:

• Copias de seguridad, parches y escalado sencillo.
• Funciona de forma independiente del servidor de la aplicación (EC2).
• Alta disponibilidad y durabilidad de los datos.

En database.tf definimos primero la red de RDS. RDS necesita un grupo de subnets en al menos dos zonas de disponibilidad (availability zones):

resource "aws_db_subnet_group" "default" {
  name       = "django-db-subnet-group"
  subnet_ids = [
    aws_subnet.public.id,       // subnet #1
    aws_subnet.public_b.id,     // subnet #2
  ]
}

Cada subnet está en una zona distinta (a y b). Si una zona falla, RDS puede seguir operando en la otra.

resource "aws_security_group" "rds_sg" {
  name   = "django-rds-sg"
  vpc_id = aws_vpc.default.id

  ingress {
    from_port   = 5432
    to_port     = 5432
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"] // Desarrollo: cualquier IP
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

Un grupo de seguridad que solo admite conexiones entrantes en el puerto de PostgreSQL (5432).

Actualizamos proyecto1/settings.py para que lea la configuración de la base de datos desde variables de entorno. Así las credenciales no quedan en el código.

Ahora el contenedor Django espera estas 5 variables de entorno para conectarse a la base de datos.

# ... otras configuraciones

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("DB_NAME"),
        "USER": os.environ.get("DB_USER"),
        "PASSWORD": os.environ.get("DB_PASSWORD"),
        "HOST": os.environ.get("DB_HOST"),
        "PORT": os.environ.get("DB_PORT"),
    }
}

Por defecto, los logs de la aplicación (stdout y stderr) se guardan dentro del contenedor. Esto trae varios problemas:

• Si el contenedor se detiene o se reemplaza, los logs se pierden.
• Tendrías que conectarte por SSH y ejecutar docker logs <id>.
• Repetirlo en varios servidores es impráctico.

La solución es enviar los logs a un servicio centralizado, como Amazon CloudWatch.

resource "aws_iam_policy" "cloudwatch_logs" {
  name   = "EC2CloudWatchLogsPolicy"
  policy = jsonencode({
    Version   = "2012-10-17",
    Statement = [{
      Effect   = "Allow",
      Action   = ["logs:CreateLogStream", "logs:PutLogEvents"],
      Resource = "arn:aws:logs:*:*:*"
    }]
  })
}

resource "aws_iam_role_policy_attachment" "ec2_logs" {
  role       = aws_iam_role.ec2_ecr.name
  policy_arn = aws_iam_policy.cloudwatch_logs.arn
}

El servidor necesita permiso para escribir en CloudWatch. Creamos una política IAM y la adjuntamos al rol de la instancia EC2.

Tras terraform apply, todos los print() y errores de Django aparecen en CloudWatch. Para verlos:

1. En la consola de AWS, busca Cloudwatch.
2. En el menú izquierdo, selecciona Logs > Log groups.
3. Abre el grupo de logs django-app-logs.

Desde ahí puedes buscar errores, filtrar por fecha y configurar alarmas.

nginx (reverse proxy y archivos estáticos):

• Recibe el tráfico público en el puerto 80 (HTTP).
• Sirve los archivos estáticos (/static/).
• Reenvía las peticiones dinámicas a Gunicorn (proxy_pass).

Gunicorn (servidor de aplicación WSGI):

• Ejecuta la aplicación Django.
• Escucha en un puerto local no expuesto (127.0.0.1:8000), solo accesible para nginx.
• Gestiona los procesos worker de Python.

nginx.conf configura nginx para servir directamente los archivos estáticos de collectstatic (cuando el usuario accede a /static/) y reenviar el resto de las solicitudes a Gunicorn, como las páginas de tu aplicación Django.

server {
    listen 80;

    location /static/ {
        alias /app/staticfiles/;
    }

    # Redirigir todas las demás solicitudes a Gunicorn
    location / {
        proxy_pass http://127.0.0.1:8000;

        # Enviar encabezados importantes al servidor de aplicación
        proxy_set_header Host $host;
    }
}

Docker está pensado para un solo proceso principal por contenedor. En producción se recomienda un contenedor para Gunicorn y otro para nginx. Como estamos en desarrollo, usaremos un único contenedor para ambos.

En Linux, da permisos de ejecución al script:

chmod +x entrypoint.sh

#!/bin/bash
set -e

python manage.py collectstatic --noinput --clear

# Inicia nginx en segundo plano
nginx -g "daemon off;" &

# Inicia Gunicorn como proceso principal
exec gunicorn proyecto1.wsgi:application --bind 127.0.0.1:8000

4. Actualiza el Dockerfile: instala nginx y copia los nuevos archivos.

RUN apt-get install -y nginx

# copiar los archivos
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY entrypoint.sh /app/entrypoint.sh

# establecer al entrypoint.sh como punto de entrada
ENTRYPOINT ["/app/entrypoint.sh"]

5. Cambia el mapeo de puertos en Terraform para exponer solo los puertos públicos (80/443). En el user_data de aws_instance, el puerto mapeado debe ser 80:80:

# main.tf
docker run -d -p 80:80 --restart unless-stopped \
       # ... (variables de entorno)