Un’app web con PostgreSQL, costruita un passo alla volta
Una piccola applicazione web che conserva note in PostgreSQL, sviluppata in quattro passi: parte con il suo database sulla tua macchina, aggiunge una cache Redis, passa su AWS con il database su Amazon RDS e infine ottiene i suoi backup. Ogni passo è un workspace completo a sé, nelle directory da 1/ a 4/, e per ciascuno la build riesce così com’è.
Ogni aggregate.yaml si apre con un commento di una riga che nomina il suo passo, e lo stesso fa un release.yaml o un manifest.yaml dove quel passo lo modifica. Confrontare un file con quello del passo precedente mostra esattamente ciò che il passo aggiunge:
diff 1/aggregate.yaml 2/aggregate.yamlL’applicazione è hub.aggrega.ai/tools/quickstart-web:1.1.0, con licenza Apache-2.0. Legge la propria configurazione soltanto dal proprio ambiente: PGHOST, PGPORT, PGUSER, PGPASSWORD e PGDATABASE per PostgreSQL, e REDIS_HOST e REDIS_PORT per una cache, che usa solo finché REDIS_HOST è impostata. È in ascolto sulla porta 8080, e ogni risposta su una nota dice da dove la nota è stata letta, nel suo campo source, così la cache è visibile dall’esterno.
I blocchi di output in questa pagina sono copiati da un’esecuzione reale, secondo Leggere l’output in queste pagine.
Cosa ti serve
- La CLI
aggrega, per ogni passo. - Docker con Compose, per
1/e2/, che vengono eseguiti sulla tua macchina. - Nient’altro per
3/e4/: generano file Terraform e si fermano. La prima build di ciascuno scarica i moduli RDS ed ElastiCache dai rispettivi repository git. Pianificare e applicare quei file è un atto separato, da compiere con il tuo account AWS e le tue credenziali una volta sostituiti i segnaposto.
Eseguirlo con un solo comando
Puoi eseguire il primo passo con un solo comando, oppure far scrivere e costruire l’esempio al tuo assistente AI.
Scegli una password per il database ed esportala prima di tutto. Su Linux o macOS:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shSu Windows, in PowerShell:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexLa password deve essere esportata perché Docker Compose la legge dalla tua shell, e il database conserva la prima password con cui è stato avviato, quindi il secondo passo richiede la stessa. Lo script si rifiuta di partire senza di essa.
Lo script dice che cosa farà e chiede conferma prima di proseguire. Verifica di riuscire a trovare aggrega, e che Docker risponda e disponga di Compose. Scrive l’esempio nella cartella quickstart-web, oppure usa quella cartella se esiste già. Poi compila il primo passo e lo avvia con Docker Compose. Lo script termina stampando la pagina dell’app, http://127.0.0.1:8080/.
Per eseguire un altro passo, indicalo: 2, 3 o 4; i passi 3 e 4 si limitano a compilare. Su Linux o macOS, passalo dopo sh -s -- e aggiungi lì --yes per procedere senza la domanda:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2In PowerShell, impostalo prima in QUICKSTART_STEP. Resta impostato in quella finestra, per ogni esecuzione successiva, finché non lo rimuovi con Remove-Item Env:QUICKSTART_STEP:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexGenerare l’esempio
Se preferisci compilarlo ed eseguirlo passo per passo, scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example quickstart-webPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd quickstart-webBuild
I comandi seguenti avviano il primo passo, dalla directory di questo esempio. La password la scegli tu: Docker Compose la legge dalla tua shell quando lo stack si avvia, quindi nessun file la contiene.
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 browserLa build scrive un solo file, dist/compose/docker-compose.yaml, e docker compose lo avvia con il nome di progetto quickstart-web e ritorna non appena entrambi i servizi sono attivi. Ogni sezione seguente fa un passo in più.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare alcuna cartella da solo. Se la cartella del workspace non contiene ancora una cartella `quickstart-web`, chiama una volta lo strumento `scaffold` con `example` impostato a `quickstart-web` e senza `dir`: scrive l’esempio in una nuova cartella `quickstart-web`, con un README e le cartelle dei passi da `1` a `4`. Poi chiama lo strumento `build` con `workspace_root` impostato a `quickstart-web/1`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `quickstart-web/1/dist/`.Un’app web e il suo PostgreSQL — 1/
L’Aggregate dichiara due componenti: web, di tipo core/compute/server, e db, di tipo core/datastore/postgres. L’applicazione chiede il database su un arco, con i nomi che legge:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseLa password raggiunge entrambe le estremità tramite un’associazione core/secret-value su ciascuna, la cui origine è il riferimento alla variabile Compose ${QUICKSTART_DB_PASSWORD}. La Release nomina l’immagine, fissata tramite il digest del suo indice multipiattaforma, la porta su cui è in ascolto, port: 8080, e published_port: 8080, la porta pubblicata per essa sulla tua macchina; senza published_port lì non viene pubblicato nulla. Il servizio web 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 è db, il nome del servizio del database sulla rete Compose, e la porta è pubblicata soltanto sull’indirizzo di loopback della tua macchina.
Apri http://127.0.0.1:8080/ in un browser sulla stessa macchina per vedere la pagina dell’app. La pagina indica il database e la cache a cui l’app è connessa, e ti permette di aggiungere una nota e di leggerla. Ogni lettura dice da dove proviene, «from PostgreSQL» o «from the cache». Finché non è collegata alcuna cache, la pagina riporta «No cache is wired to the app, so every read comes from PostgreSQL.»
Da un terminale, chiedi all’applicazione a cosa è connessa, poi memorizza una nota e rileggila:
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"}Aggiungere una cache — 2/
L’Aggregate aggiunge un componente cache di tipo core/datastore/redis, e un arco in più sull’applicazione:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portIl Manifest mappa il nuovo tipo su compose/redis, e la Release colloca il nuovo componente. Esegui la build e avvialo con lo stesso nome di progetto, con la stessa password ancora esportata:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose lascia in esecuzione il database, ricrea l’applicazione con le sue due nuove variabili e avvia la cache. Il database è stato creato con la password che hai esportato in 1/ e la conserva, quindi mantieni lo stesso valore per questo passo. La nota memorizzata in 1/ è ancora lì; leggila due volte:
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"}La prima lettura proviene da PostgreSQL e riempie la cache; la seconda proviene dalla cache, che conserva una nota per cinque minuti. Nella pagina, leggere una nota due volte mostra «from PostgreSQL», poi «from the cache».
Quando hai finito con lo stack, rimuovilo, insieme ai dati del database:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -vStesso database, gestito su AWS — 3/
Gli stessi tre componenti, su AWS, tramite Terraform. Il Manifest mappa il server su terraform/server-ecs, un servizio Amazon ECS su Fargate; PostgreSQL su terraform/postgres-rds-terraform-aws-modules, che incorpora una copia del modulo RDS pubblicato dal progetto terraform-aws-modules; e Redis su terraform/redis-elasticache, che incorpora una copia del suo modulo ElastiCache. Gli archi nell’Aggregate non cambiano.
Ciò che l’Aggregate elimina sono le due associazioni della password: RDS genera da sé la password del database, quindi nessun input della build ne porta una. Su AWS, RDS conserva la password in AWS Secrets Manager, e l’applicazione quickstart, che legge la propria password solo da PGPASSWORD, non può autenticarsi finché non la fornisci.
La Release nomina, sotto infra.overrides, ciò che esegui già nel tuo account: il cluster ECS, le subnet e i security group a cui si collegano i task, il ruolo di esecuzione con cui ECS scarica l’immagine e scrive i log, e i subnet group di RDS ed ElastiCache. Imposta inoltre l’engine_version della cache a 7.1, perché ElastiCache esegue Redis OSS fino alla 7.1. Ognuno di questi valori è un segnaposto: 123456789012 è il numero di account che la documentazione AWS usa negli esempi, e gli ID subnet-… e sg-…, i subnet group, il cluster e il ruolo stanno per risorse nel tuo account. La build li accetta perché non li cerca mai; sostituiscili prima di pianificare.
cd ../3aggrega build --release release.yaml --auto-pullLa configurazione radice, 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"]}L’applicazione riceve gli stessi nomi che su Compose. PGHOST e REDIS_HOST sono ora riferimenti agli output propri dei moduli RDS ed ElastiCache, che Terraform risolve quando applica la configurazione, perché nessuno dei due indirizzi esiste prima che l’istanza e la cache vengano create; il compilatore li convoglia entrambi senza leggerli. Su una copia di dist/terraform, tofu init -backend=false carica la radice e i moduli incorporati e scarica soltanto i provider, e tofu validate stampa poi:
Success! The configuration is valid.Aggiungere i backup — 4/
RDS conserva i backup automatici dell’istanza per 7 giorni, in una finestra che sceglie da sé, quando nulla dice altrimenti — backup_retention_period = 7 sopra. La Release associa core/backup al database:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"e il Manifest lega la Feature a terraform/backup-native, che non renderizza nulla di proprio: il backup è un’impostazione dell’istanza, quindi la Recipe del database legge l’associazione e la scrive nel blocco del modulo dell’istanza. RDS esegue un backup automatico al giorno, quindi la programmazione apre una finestra di 30 minuti a quell’ora, in UTC. L’Aggregate non cambia.
cd ../4aggrega build --release release.yaml --auto-pullLa configurazione radice differisce da quella di 3/ soltanto nel blocco del modulo db, e anche su di essa tofu validate stampa Success! The configuration is valid.:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Eseguire il build non è distribuire
3/ e 4/ scrivono file sotto dist/ e si fermano. La build non esegue mai Terraform né OpenTofu, non si autentica mai su AWS e non cerca nessuno degli identificatori che le Releases nominano. Pianificare e applicare sono passi che compi sull’output, con le tue credenziali, dopo aver sostituito i segnaposto.
Verificare ogni passo
In un checkout del repository della documentazione, che contiene l’helper di build condiviso che una copia scritta da aggrega scaffold --example non porta con sé, ./check.sh in questa directory esegue la build dei quattro passi e verifica che ciascuno scriva ciò che questa pagina mostra: i due file Compose con i loro servizi e le loro variabili, e le due configurazioni radice Terraform con i loro blocchi di modulo, i loro riferimenti e le loro impostazioni di backup. Stampa una riga per passo ed esce con un codice diverso da zero se un passo differisce. dist/, .aggrega/ e i file *.lock sono generati e non vengono committati; si rigenerano dai file che lo sono.