Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Una aplicación web con PostgreSQL, construida paso a paso

Una pequeña aplicación web que guarda notas en PostgreSQL, desarrollada en cuatro pasos: empieza con su base de datos en tu máquina, incorpora una caché Redis, pasa a AWS con la base de datos en Amazon RDS y, por último, obtiene sus copias de seguridad. Cada paso es un espacio de trabajo completo por sí mismo, en los directorios 1/ a 4/, y cada uno se compila tal como está.

Cada aggregate.yaml comienza con un comentario de una línea que nombra su paso, y lo mismo hace un release.yaml o un manifest.yaml cuando ese paso lo modifica. Comparar un archivo con el del paso anterior muestra exactamente lo que el paso añade:

Terminal window
diff 1/aggregate.yaml 2/aggregate.yaml

La aplicación es hub.aggrega.ai/tools/quickstart-web:1.1.0, bajo la licencia Apache-2.0. Lee su configuración únicamente de su entorno: PGHOST, PGPORT, PGUSER, PGPASSWORD y PGDATABASE para PostgreSQL, y REDIS_HOST y REDIS_PORT para una caché, que usa solo mientras REDIS_HOST esté definida. Escucha en el puerto 8080, y cada respuesta sobre una nota indica de dónde se leyó la nota, en su campo source, de modo que la caché es visible desde fuera.

Los bloques de salida de esta página están copiados de una ejecución real, según Leer la salida en estas páginas.

Lo que necesitas

  • La CLI aggrega, para cada paso.
  • Docker con Compose, para 1/ y 2/, que se ejecutan en tu máquina.
  • Nada más para 3/ y 4/: compilan archivos de Terraform y se detienen. La primera compilación de cada uno obtiene los módulos de RDS y ElastiCache de sus repositorios git. Planificar y aplicar esos archivos es un acto aparte, que se hace con tu propia cuenta de AWS y tus credenciales una vez sustituidos los marcadores de posición.

Ejecutarlo con un solo comando

Puedes ejecutar el primer paso con un solo comando, o hacer que tu asistente de IA lo escriba y lo compile por ti.

Elige una contraseña para la base de datos y expórtala primero. En Linux o macOS:

Terminal window
export QUICKSTART_DB_PASSWORD=choose-a-password
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh

En Windows, en PowerShell:

Terminal window
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'
irm https://aggrega.ai/quickstart-web.ps1 | iex

La contraseña debe exportarse porque Docker Compose la lee de tu shell, y la base de datos conserva la primera contraseña con la que se inició, así que el segundo paso necesita la misma. El script se niega a iniciarse sin ella.

El script indica lo que hará y pregunta antes de continuar. Comprueba que puede encontrar aggrega, y que Docker responde y tiene Compose. Escribe el ejemplo en la carpeta quickstart-web, o usa esa carpeta si ya existe. Después compila el primer paso y lo inicia con Docker Compose. El script termina mostrando la página de la aplicación, http://127.0.0.1:8080/.

Para ejecutar otro paso, indícalo: 2, 3 o 4; los pasos 3 y 4 solo compilan. En Linux o macOS, pásalo después de sh -s -- y añade ahí --yes para continuar sin la pregunta:

Terminal window
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2

En PowerShell, establécelo primero en QUICKSTART_STEP. Queda establecido en esa ventana, para cada ejecución posterior, hasta que lo quites con Remove-Item Env:QUICKSTART_STEP:

Terminal window
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iex

Generar el ejemplo

Si prefieres compilarlo y ejecutarlo paso a paso, escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example quickstart-web

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd quickstart-web

Compilación

Los comandos siguientes inician el primer paso, desde el directorio de este ejemplo. La contraseña la eliges tú: Docker Compose la lee de tu shell cuando se inicia el stack, así que ningún archivo la contiene.

Terminal window
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait
# then open http://127.0.0.1:8080/ in your browser

La compilación escribe un único archivo, dist/compose/docker-compose.yaml, y docker compose lo inicia con el nombre de proyecto quickstart-web y retorna en cuanto ambos servicios están activos. Cada sección siguiente avanza un paso más.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `quickstart-web`, llama una vez a la herramienta `scaffold` con `example` establecido en `quickstart-web` y sin `dir`: escribe el ejemplo en una nueva carpeta `quickstart-web`, con un README y las carpetas de pasos `1` a `4`. Luego llama a la herramienta `build` con `workspace_root` establecido en `quickstart-web/1`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `quickstart-web/1/dist/`.

Una aplicación web y su PostgreSQL — 1/

El Aggregate declara dos componentes: web, de tipo core/compute/server, y db, de tipo core/datastore/postgres. La aplicación pide la base de datos en una arista, con los nombres que lee:

uses:
database:
db:
target: db
inject:
env:
- in: PGHOST
from: host
- in: PGPORT
from: port
- in: PGUSER
from: user
- in: PGDATABASE
from: database

La contraseña llega a ambos extremos mediante una vinculación core/secret-value en cada uno, cuyo origen es la referencia a variable de Compose ${QUICKSTART_DB_PASSWORD}. La Release nombra la imagen, fijada por el digest de su índice multiplataforma, el puerto en el que escucha, port: 8080, y published_port: 8080, el puerto que se publica para ella en tu máquina; sin published_port no se publica nada allí. El servicio web en dist/compose/docker-compose.yaml:

web:
image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:72d42d6db51d34d1268108eca1989e1467ccb2c66d15ed3e50ca97e09003c8fb
environment:
PGDATABASE: appdb
PGHOST: db
PGPASSWORD: ${QUICKSTART_DB_PASSWORD}
PGPORT: "5432"
PGUSER: appuser
ports:
- 127.0.0.1:8080:8080
[… omitted: the aggrega.ai/ labels every service carries]
networks:
- compose
depends_on:
- db
deploy:
resources:
limits:
cpus: "0.1"
memory: "134217728"
reservations:
cpus: "0.1"
memory: "134217728"

PGHOST es db, el nombre de servicio de la base de datos en la red de Compose, y el puerto se publica solo en la dirección de loopback de tu máquina.

Abre http://127.0.0.1:8080/ en un navegador en la misma máquina para ver la página de la aplicación. Indica la base de datos y la caché a las que está conectada la aplicación, y te permite añadir una nota y leerla. Cada lectura indica de dónde vino, «from PostgreSQL» o «from the cache». Mientras no haya ninguna caché conectada, la página dice «No cache is wired to the app, so every read comes from PostgreSQL.»

Desde una terminal, pregunta a la aplicación a qué está conectada, luego guarda una nota y vuelve a leerla:

Terminal window
curl -s http://localhost:8080/
curl -s -X POST --data 'hello from the quickstart' http://localhost:8080/notes
curl -s http://localhost:8080/notes/1
{
"cache": "not wired",
"database": "postgresql at db:5432/appdb",
"service": "quickstart-web"
}
{
"id": 1,
"text": "hello from the quickstart",
"created_at": "2026-11-01T17:22:34.261989Z",
"source": "postgresql"
}
{
"id": 1,
"text": "hello from the quickstart",
"created_at": "2026-11-01T17:22:34.261989Z",
"source": "postgresql"
}

Añadir una caché — 2/

El Aggregate añade un componente cache de tipo core/datastore/redis, y una arista más en la aplicación:

cache:
cache:
target: cache
inject:
env:
- in: REDIS_HOST
from: host
- in: REDIS_PORT
from: port

El Manifest asigna el nuevo tipo a compose/redis, y la Release coloca el nuevo componente. Compílalo e inícialo con el mismo nombre de proyecto, con la misma contraseña todavía exportada:

Terminal window
cd ../2
aggrega build --release release.yaml --auto-pull
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait

Docker Compose deja la base de datos en ejecución, vuelve a crear la aplicación con sus dos nuevas variables e inicia la caché. La base de datos se creó con la contraseña que exportaste en 1/ y la conserva, así que mantén el mismo valor para este paso. La nota guardada en 1/ sigue ahí; léela dos veces:

Terminal window
curl -s http://localhost:8080/
curl -s http://localhost:8080/notes/1
curl -s http://localhost:8080/notes/1
{
"cache": "cache:6379",
"database": "postgresql at db:5432/appdb",
"service": "quickstart-web"
}
{
"id": 1,
"text": "hello from the quickstart",
"created_at": "2026-11-01T17:22:34.261989Z",
"source": "postgresql"
}
{
"id": 1,
"text": "hello from the quickstart",
"created_at": "2026-11-01T17:22:34.261989Z",
"source": "cache"
}

La primera lectura viene de PostgreSQL y llena la caché; la segunda viene de la caché, que conserva una nota durante cinco minutos. En la página, leer una nota dos veces muestra «from PostgreSQL» y luego «from the cache».

Cuando termines con el stack, elimínalo, junto con los datos de la base de datos:

Terminal window
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -v

La misma base de datos, gestionada en AWS — 3/

Los mismos tres componentes, en AWS, mediante Terraform. El Manifest asigna el servidor a terraform/server-ecs, un servicio de Amazon ECS en Fargate; PostgreSQL a terraform/postgres-rds-terraform-aws-modules, que incorpora una copia del módulo RDS publicado por el proyecto terraform-aws-modules; y Redis a terraform/redis-elasticache, que incorpora una copia de su módulo ElastiCache. Las aristas del Aggregate no cambian.

Lo que el Aggregate elimina son las dos vinculaciones de contraseña: RDS genera por sí mismo la contraseña de la base de datos, así que ninguna entrada de la compilación lleva una. En AWS, RDS guarda la contraseña en AWS Secrets Manager, y la aplicación quickstart, que lee su contraseña solo de PGPASSWORD, no puede iniciar sesión hasta que la proporciones.

La Release nombra, bajo infra.overrides, lo que ya ejecutas en tu cuenta: el clúster de ECS, las subredes y los grupos de seguridad a los que se conectan las tareas, el rol de ejecución con el que ECS descarga la imagen y escribe los logs, y los grupos de subredes de RDS y ElastiCache. También establece el engine_version de la caché en 7.1, porque ElastiCache ejecuta Redis OSS hasta la 7.1. Cada uno de esos valores es un marcador de posición: 123456789012 es el número de cuenta que la documentación de AWS usa en los ejemplos, y los ID subnet-… y sg-…, los grupos de subredes, el clúster y el rol representan recursos de tu propia cuenta. La compilación los acepta porque nunca los consulta; sustitúyelos antes de planificar.

Terminal window
cd ../3
aggrega build --release release.yaml --auto-pull

La configuración raíz, dist/terraform/aggrega.modules.tf:

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "cache" {
source = "./modules/cache"
create_security_group = false
create_subnet_group = false
engine = "redis"
engine_version = "7.1"
node_type = "cache.t3.small"
port = 6379
replication_group_id = "cache"
security_group_ids = ["sg-0123456789abcdef1"]
subnet_group_name = "example-private-cache-subnets"
transit_encryption_enabled = false
}
module "db" {
source = "./modules/db"
allocated_storage = 10
backup_retention_period = 7
create_db_subnet_group = false
db_name = "appdb"
db_subnet_group_name = "example-private-db-subnets"
engine = "postgres"
engine_version = "16"
family = "postgres16"
identifier = "db"
instance_class = "db.t3.small"
manage_master_user_password = true
multi_az = false
port = "5432"
skip_final_snapshot = false
storage_type = "gp3"
username = "appuser"
vpc_security_group_ids = ["sg-0123456789abcdef0"]
}
module "web" {
source = "./modules/web"
assign_public_ip = false
cluster = "example-cluster"
cpu = "256"
desired_count = 1
environment = {"PGDATABASE":"appdb","PGHOST":"${module.db.db_instance_address}","PGPORT":"5432","PGUSER":"appuser","REDIS_HOST":"${module.cache.replication_group_primary_endpoint_address}","REDIS_PORT":"6379"}
execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution"
image = "hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:72d42d6db51d34d1268108eca1989e1467ccb2c66d15ed3e50ca97e09003c8fb"
memory = "512"
name = "web"
port = 8080
security_groups = ["sg-0fedcba9876543210"]
subnet_ids = ["subnet-0123456789abcdef0","subnet-0fedcba9876543210"]
}

La aplicación recibe los mismos nombres que en Compose. PGHOST y REDIS_HOST son ahora referencias a las salidas propias de los módulos de RDS y ElastiCache, que Terraform resuelve cuando aplica la configuración, porque ninguna de las dos direcciones existe antes de que se creen la instancia y la caché; el compilador canaliza ambas sin leerlas. En una copia de dist/terraform, tofu init -backend=false carga la raíz y los módulos incorporados y obtiene solo los proveedores, y tofu validate imprime entonces:

Success! The configuration is valid.

Añadir copias de seguridad — 4/

RDS conserva las copias de seguridad automatizadas de la instancia durante 7 días, en una ventana que elige él mismo, cuando nada indica lo contrario — backup_retention_period = 7 arriba. La Release vincula core/backup a la base de datos:

db:
features:
backup:
type: core/backup
infra:
retention_days: 14
schedule: "30 2 * * *"

y el Manifest enlaza la Feature con terraform/backup-native, que no renderiza nada propio: la copia de seguridad es un ajuste de la instancia, así que la Recipe de la base de datos lee la vinculación y la escribe en el bloque del módulo de la instancia. RDS hace una copia de seguridad automatizada al día, así que la programación abre una ventana de 30 minutos a esa hora, en UTC. El Aggregate no cambia.

Terminal window
cd ../4
aggrega build --release release.yaml --auto-pull

La configuración raíz difiere de la de 3/ solo en el bloque del módulo db, y tofu validate sobre ella imprime también Success! The configuration is valid.:

backup_retention_period = 7
backup_retention_period = 14
backup_window = "02:30-03:00"

Compilar no es desplegar

3/ y 4/ escriben archivos en dist/ y se detienen. La compilación nunca ejecuta Terraform ni OpenTofu, nunca se autentica en AWS y no consulta ninguno de los identificadores que nombran las Releases. Planificar y aplicar son pasos que das sobre la salida, con tus propias credenciales, después de sustituir los marcadores de posición.

Comprobar cada paso

En un checkout del repositorio de la documentación, que contiene el script auxiliar de compilación compartido que una copia escrita por aggrega scaffold --example no incluye, ./check.sh en este directorio compila los cuatro pasos y comprueba que cada uno escribe lo que muestra esta página: los dos archivos de Compose con sus servicios y variables, y las dos configuraciones raíz de Terraform con sus bloques de módulo, sus referencias y sus ajustes de copia de seguridad. Imprime una línea por paso y termina con un código distinto de cero si algún paso difiere. dist/, .aggrega/ y los archivos *.lock se generan y no se confirman; se regeneran a partir de los archivos que sí lo están.