Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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:

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

L’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/ e 2/, che vengono eseguiti sulla tua macchina.
  • Nient’altro per 3/ e 4/: 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:

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

Su Windows, in PowerShell:

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

La 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:

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

In 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:

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

Generare l’esempio

Se preferisci compilarlo ed eseguirlo passo per passo, scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example quickstart-web

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd quickstart-web

Build

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.

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 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: database

La 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:

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"
}

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: port

Il 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:

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 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:

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 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:

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

Stesso 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.

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

La 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.

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

La 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 = 7
backup_retention_period = 14
backup_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.