Uma aplicação web com PostgreSQL, construída passo a passo
Uma pequena aplicação web que guarda notas no PostgreSQL, desenvolvida em quatro passos: começa com a sua base de dados na sua máquina, ganha uma cache Redis, passa para a AWS com a base de dados no Amazon RDS e, por fim, recebe as suas cópias de segurança. Cada passo é um espaço de trabalho completo por si só, nos diretórios 1/ a 4/, e cada um compila tal como está.
Cada aggregate.yaml abre com um comentário de uma linha que nomeia o seu passo, e o mesmo faz um release.yaml ou um manifest.yaml onde esse passo o altera. Comparar um ficheiro com o do passo anterior mostra exatamente o que o passo acrescenta:
diff 1/aggregate.yaml 2/aggregate.yamlA aplicação é hub.aggrega.ai/tools/quickstart-web:1.1.0, sob a licença Apache-2.0. Lê a sua configuração apenas do seu ambiente: PGHOST, PGPORT, PGUSER, PGPASSWORD e PGDATABASE para o PostgreSQL, e REDIS_HOST e REDIS_PORT para uma cache, que usa apenas enquanto REDIS_HOST estiver definida. Escuta na porta 8080, e cada resposta sobre uma nota indica de onde a nota foi lida, no seu campo source, pelo que a cache é visível do exterior.
Os blocos de saída desta página são copiados de uma execução real, conforme Ler a saída nestas páginas.
O que é necessário
- A CLI
aggrega, para todos os passos. - Docker com Compose, para
1/e2/, que são executados na sua máquina. - Nada mais para
3/e4/: compilam ficheiros do Terraform e param. A primeira compilação de cada um obtém os módulos do RDS e do ElastiCache dos respetivos repositórios git. Planear e aplicar esses ficheiros é um ato separado, feito com a sua própria conta da AWS e as suas credenciais depois de substituídos os marcadores de posição.
Executar com um único comando
É possível executar o primeiro passo com um único comando ou pedir ao assistente de IA que o escreva e o compile.
Escolha uma palavra-passe para a base de dados e exporte-a primeiro. Em Linux ou macOS:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shNo Windows, no PowerShell:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexA palavra-passe tem de ser exportada porque o Docker Compose a lê da shell, e a base de dados mantém a primeira palavra-passe com que foi iniciada, pelo que o segundo passo precisa da mesma. O script recusa-se a arrancar sem ela.
O script diz o que vai fazer e pergunta antes de prosseguir. Verifica se consegue encontrar aggrega, e se o Docker responde e tem o Compose. Escreve o exemplo na pasta quickstart-web, ou usa essa pasta quando já existe. Depois, compila o primeiro passo e inicia-o com o Docker Compose. No fim, o script apresenta a página da aplicação, http://127.0.0.1:8080/.
Para executar outro passo, indique-o: 2, 3 ou 4; os passos 3 e 4 apenas compilam. No Linux ou no macOS, indique-o depois de sh -s -- e acrescente aí --yes para avançar sem a pergunta:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2No PowerShell, defina-o primeiro em QUICKSTART_STEP. Fica definido nessa janela, para todas as execuções seguintes, até o remover com Remove-Item Env:QUICKSTART_STEP:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexGerar o exemplo
Se preferir compilá-lo e executá-lo passo a passo, escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example quickstart-webDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd quickstart-webCompilação
Os comandos abaixo iniciam o primeiro passo, a partir do diretório deste exemplo. A palavra-passe é escolhida por si: o Docker Compose lê-a da sua shell quando a stack arranca, pelo que nenhum ficheiro a contém.
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 browserA compilação escreve um único ficheiro, dist/compose/docker-compose.yaml, e docker compose inicia-o com o nome de projeto quickstart-web e regressa assim que os dois serviços estão em execução. Cada secção abaixo avança mais um passo.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa própria. Se a pasta do espaço de trabalho ainda não contiver uma pasta `quickstart-web`, chame uma vez a ferramenta `scaffold` com `example` definido como `quickstart-web` e sem `dir`: esta escreve o exemplo numa nova pasta `quickstart-web`, com um README e as pastas de passo `1` a `4`. Depois chame a ferramenta `build` com `workspace_root` definido como `quickstart-web/1`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros o build escreveu; encontram-se em `quickstart-web/1/dist/`.Uma aplicação web e o seu PostgreSQL — 1/
O Aggregate declara dois componentes: web, do tipo core/compute/server, e db, do tipo core/datastore/postgres. A aplicação pede a base de dados numa aresta, com os nomes que lê:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseA palavra-passe chega às duas pontas através de um anexo core/secret-value em cada uma, cuja origem é a referência à variável do Compose ${QUICKSTART_DB_PASSWORD}. A Release nomeia a imagem, fixada pelo digest do seu índice multiplataforma, a porta em que esta escuta, port: 8080, e published_port: 8080, a porta publicada para ela na máquina; sem published_port, nada é aí publicado. O serviço web em 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, o nome de serviço da base de dados na rede do Compose, e a porta é publicada apenas no endereço de loopback da sua máquina.
Abra http://127.0.0.1:8080/ num navegador na mesma máquina para ver a página da aplicação. A página indica a base de dados e a cache a que a aplicação está ligada, e permite acrescentar uma nota e lê-la. Cada leitura indica de onde veio, «from PostgreSQL» ou «from the cache». Enquanto não houver nenhuma cache ligada, a página apresenta «No cache is wired to the app, so every read comes from PostgreSQL.»
Num terminal, pergunte à aplicação a que está ligada e, depois, guarde uma nota e volte a lê-la:
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"}Adicionar uma cache — 2/
O Aggregate adiciona um componente cache do tipo core/datastore/redis, e mais uma aresta na aplicação:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portO Manifest mapeia o novo tipo para compose/redis, e a Release coloca o novo componente. Compile-o e inicie-o com o mesmo nome de projeto, com a mesma palavra-passe ainda exportada:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitO Docker Compose deixa a base de dados em execução, recria a aplicação com as suas duas novas variáveis e inicia a cache. A base de dados foi criada com a palavra-passe que exportou em 1/ e mantém-na, pelo que deve manter o mesmo valor neste passo. A nota guardada em 1/ continua lá; leia-a duas vezes:
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"}A primeira leitura vem do PostgreSQL e preenche a cache; a segunda vem da cache, que guarda uma nota durante cinco minutos. Na página, ler uma nota duas vezes mostra «from PostgreSQL» e depois «from the cache».
Quando terminar de usar a stack, remova-a, juntamente com os dados da base de dados:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -vA mesma base de dados, gerida na AWS — 3/
Os mesmos três componentes, na AWS, através do Terraform. O Manifest mapeia o servidor para terraform/server-ecs, um serviço do Amazon ECS no Fargate; o PostgreSQL para terraform/postgres-rds-terraform-aws-modules, que incorpora uma cópia do módulo RDS publicado pelo projeto terraform-aws-modules; e o Redis para terraform/redis-elasticache, que incorpora uma cópia do seu módulo ElastiCache. As arestas no Aggregate não mudam.
O que o Aggregate descarta são os dois anexos de palavra-passe: o RDS gera ele próprio a palavra-passe da base de dados, pelo que nenhuma entrada da compilação contém uma. Na AWS, o RDS guarda a palavra-passe no AWS Secrets Manager, e a aplicação quickstart, que lê a sua palavra-passe apenas de PGPASSWORD, não consegue autenticar-se até que a forneça.
A Release nomeia, sob infra.overrides, o que já executa na sua conta: o cluster ECS, as sub-redes e os grupos de segurança aos quais as tarefas se ligam, a função de execução com que o ECS obtém a imagem e escreve os logs, e os grupos de sub-redes do RDS e do ElastiCache. Também define o engine_version da cache como 7.1, porque o ElastiCache executa o Redis OSS até à 7.1. Cada um desses valores é um marcador de posição: 123456789012 é o número de conta que a documentação da AWS usa nos exemplos, e os ID subnet-… e sg-…, os grupos de sub-redes, o cluster e a função representam recursos na sua própria conta. A compilação aceita-os porque nunca os consulta; substitua-os antes de planear.
cd ../3aggrega build --release release.yaml --auto-pullA configuração raiz, 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"]}A aplicação recebe os mesmos nomes que no Compose. PGHOST e REDIS_HOST são agora referências às saídas próprias dos módulos do RDS e do ElastiCache, que o Terraform resolve quando aplica a configuração, porque nenhum dos dois endereços existe antes de a instância e a cache serem criadas; o compilador canaliza ambos sem os ler. Numa cópia de dist/terraform, tofu init -backend=false carrega a raiz e os módulos incorporados e obtém apenas os fornecedores, e tofu validate imprime então:
Success! The configuration is valid.Adicionar cópias de segurança — 4/
O RDS mantém as cópias de segurança automatizadas da instância durante 7 dias, numa janela que ele próprio escolhe, quando nada diz o contrário — backup_retention_period = 7 acima. A Release anexa core/backup à base de dados:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"e o Manifest associa a Feature a terraform/backup-native, que não renderiza nada de próprio: a cópia de segurança é uma definição da instância, pelo que a Recipe da base de dados lê o anexo e escreve-o no bloco do módulo da instância. O RDS faz uma cópia de segurança automatizada por dia, pelo que o agendamento abre uma janela de 30 minutos a essa hora, em UTC. O Aggregate não muda.
cd ../4aggrega build --release release.yaml --auto-pullA configuração raiz difere da de 3/ apenas no bloco do módulo db, e tofu validate sobre ela também imprime Success! The configuration is valid.:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Compilar não é implementar
3/ e 4/ escrevem ficheiros em dist/ e param. A compilação nunca executa o Terraform nem o OpenTofu, nunca se autentica na AWS e não consulta nenhum dos identificadores que as Releases nomeiam. Planear e aplicar são passos que executa sobre a saída, com as suas próprias credenciais, depois de substituir os marcadores de posição.
Verificar cada passo
Num checkout do repositório da documentação, que contém o auxiliar de compilação partilhado que uma cópia escrita por aggrega scaffold --example não traz, ./check.sh neste diretório compila os quatro passos e verifica que cada um escreve o que esta página mostra: os dois ficheiros do Compose com os seus serviços e variáveis, e as duas configurações raiz do Terraform com os seus blocos de módulo, as suas referências e as suas definições de cópia de segurança. Imprime uma linha por passo e termina com um código diferente de zero se algum passo divergir. dist/, .aggrega/ e os ficheiros *.lock são gerados e não são submetidos a commit; regeneram-se a partir dos ficheiros que o são.