A web app with PostgreSQL, built up one step at a time
A small web application that keeps notes in PostgreSQL, grown in four steps:
it starts with its database on your machine, gains a Redis cache, moves to AWS
with the database on Amazon RDS, and finally gets its backups. Each step is a
complete workspace of its own, in the directories 1/ to 4/, and each one
builds as it stands.
Every aggregate.yaml opens with a one-line comment naming its step, and so
does a release.yaml or a manifest.yaml where that step changes it.
Comparing a file with the previous step’s shows exactly what the step adds:
diff 1/aggregate.yaml 2/aggregate.yamlThe application is hub.aggrega.ai/tools/quickstart-web:1.1.0, under the
Apache-2.0 licence. It reads its configuration from its environment alone:
PGHOST, PGPORT, PGUSER, PGPASSWORD and PGDATABASE for PostgreSQL, and
REDIS_HOST and REDIS_PORT for a cache, which it uses only while
REDIS_HOST is set. It listens on port 8080, and every answer about a note
says where the note was read from, in its source field, so the cache is
visible from outside.
Output blocks on this page are copied from a real run, per Reading the output on these pages.
What you need
- The
aggregaCLI, for every step. - Docker with Compose, for
1/and2/, which run on your machine. - Nothing more for
3/and4/: they build Terraform files and stop. The first build of each fetches the RDS and ElastiCache modules from their git repositories. Planning and applying those files is a separate act, done with your own AWS account and credentials once the placeholders are replaced.
Run it in one command
You can run the first step with one command, or have your AI assistant write and build it for you.
Choose a password for the database and export it first. On Linux or macOS:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shOn Windows, in PowerShell:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexThe password must be exported because Docker Compose reads it from your shell, and the database keeps the first password it was started with, so the second step needs the same one. The script refuses to start without it.
The script says what it will do and asks before it goes on. It checks that it
can find aggrega, and that Docker answers and has Compose. It writes the
example into the folder quickstart-web, or uses that folder when it is
already there. It then builds the first step and starts it with Docker
Compose. The script ends by printing the app’s page,
http://127.0.0.1:8080/.
To run another step, name it: 2, 3 or 4; steps 3 and 4 only build. On
Linux or macOS, give it after sh -s --, and add --yes there to go ahead
without the question:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2In PowerShell, set it in QUICKSTART_STEP first. It stays set in that window,
for every later run, until you remove it with
Remove-Item Env:QUICKSTART_STEP:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexScaffold the example
If you prefer to build and run it step by step, write the example into a new folder named after it:
aggrega scaffold --example quickstart-webIt then prints the commands to run next. The first changes into the new folder:
cd quickstart-webBuild
The commands below start the first step, from this example’s directory. The password is yours to choose: Docker Compose reads it from your shell when the stack starts, so no file holds it.
cd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browserThe build writes one file, dist/compose/docker-compose.yaml, and
docker compose starts it under the project name quickstart-web and returns
once both services are up. Each section below takes one step further.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `quickstart-web` folder yet, call the `scaffold` tool once with `example` set to `quickstart-web` and no `dir`: it writes the example into a new `quickstart-web` folder, with a README and the step folders `1` to `4`. Then call the `build` tool with `workspace_root` set to `quickstart-web/1`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `quickstart-web/1/dist/`.A web app and its PostgreSQL — 1/
The Aggregate declares two components: web, of type core/compute/server,
and db, of type core/datastore/postgres. The application asks for the
database on an edge, under the names it reads:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseThe password reaches both ends through a core/secret-value attachment on
each, whose origin is the Compose variable reference
${QUICKSTART_DB_PASSWORD}. The Release names the image, pinned by the digest
of its multi-platform index, the port it listens on, port: 8080, and
published_port: 8080, the port published for it on your machine; without
published_port nothing is published there. The web service in
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 is db, the database’s service name on the Compose network, and the
port is published on your machine’s loopback address alone.
Open http://127.0.0.1:8080/ in a browser on the same machine to see the app’s page. It names the database and the cache the app is connected to, and lets you add a note and read it. Each read says where it came from, “from PostgreSQL” or “from the cache”. With no cache wired yet, the page says “No cache is wired to the app, so every read comes from PostgreSQL.”
From a terminal, ask the application what it is connected to, then store a note and read it back:
curl -s http://localhost:8080/curl -s -X POST --data 'hello from the quickstart' http://localhost:8080/notescurl -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"}Add a cache — 2/
The Aggregate adds a cache component of type core/datastore/redis, and one
more edge on the application:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portThe Manifest maps the new type to compose/redis, and the Release places the
new component. Build and start it under the same project name, with the same
password still exported:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose leaves the database running, recreates the application with its
two new variables, and starts the cache. The database was created with the
password you exported at 1/ and keeps it, so keep the same value for this
step. The note stored at 1/ is still there; read it twice:
curl -s http://localhost:8080/curl -s http://localhost:8080/notes/1curl -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"}The first read comes from PostgreSQL and fills the cache; the second comes from the cache, which keeps a note for five minutes. On the page, reading a note twice shows “from PostgreSQL”, then “from the cache”.
When you are done with the stack, remove it, with the database’s data:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -vSame database, managed on AWS — 3/
The same three components, on AWS, through Terraform. The Manifest maps the
server to terraform/server-ecs, an Amazon ECS service on Fargate; PostgreSQL
to terraform/postgres-rds-terraform-aws-modules, which vendors the
terraform-aws-modules project’s published RDS module; and Redis to
terraform/redis-elasticache, which vendors its ElastiCache module. The edges
in the Aggregate do not change.
What the Aggregate drops is the two password attachments: RDS generates the
database’s password itself, so no build input carries one. On AWS, RDS keeps
the password in AWS Secrets Manager, and the quickstart application, which
reads its password only from PGPASSWORD, cannot sign in until you supply it.
The Release names, under infra.overrides, what you already run in your
account: the ECS cluster, the subnets and security groups the tasks attach to,
the execution role ECS pulls the image and writes logs with, and the RDS and
ElastiCache subnet groups. It also sets the cache’s engine_version to 7.1,
because ElastiCache runs Redis OSS up to 7.1. Every one of those values is a
placeholder: 123456789012 is the account number AWS documentation uses in
examples, and the subnet-… and sg-… IDs, the subnet groups, the cluster and
the role stand for resources in your own account. The build accepts them
because it never looks them up; replace them before you plan.
cd ../3aggrega build --release release.yaml --auto-pullThe root configuration, 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"]}The application receives the same names as on Compose. PGHOST and
REDIS_HOST are now references to the RDS and ElastiCache modules’ own
outputs, which Terraform resolves when it applies the configuration, because
neither address exists before the instance and the cache are created; the
compiler pipes both through without reading them. On a copy of dist/terraform,
tofu init -backend=false loads the root and the vendored modules and fetches
only providers, and tofu validate then prints:
Success! The configuration is valid.Add backups — 4/
RDS keeps the instance’s automated backups for 7 days, in a window it chooses,
when nothing says otherwise — backup_retention_period = 7 above. The Release
attaches core/backup to the database:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"and the Manifest binds the Feature to terraform/backup-native, which renders
nothing of its own: the backup is a setting of the instance, so the database
Recipe reads the attachment and writes it on the instance’s module block. RDS
takes one automated backup a day, so the schedule opens a 30-minute window at
that time, in UTC. The Aggregate does not change.
cd ../4aggrega build --release release.yaml --auto-pullThe root configuration differs from the one at 3/ in the db module block
alone, and tofu validate on it prints Success! The configuration is valid.
as well:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Building is not deploying
3/ and 4/ write files under dist/ and stop. The build never runs
Terraform or OpenTofu, never authenticates against AWS, and looks up none of
the identifiers the Releases name. Planning and applying are steps you take on
the output, with your own credentials, after replacing the placeholders.
Checking every step
In a checkout of the documentation repository, which holds the shared build
helper a copy written by aggrega scaffold --example does not carry,
./check.sh in this directory builds the four steps and checks that each
writes what this page shows: the two Compose files with their services and
variables, and the two Terraform root configurations with their module blocks,
their references and their backup settings. It prints one line per step and
exits non-zero if any step differs. dist/, .aggrega/ and the *.lock files
are generated and are not committed; they regenerate from the files that are.