Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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: ela começa com o seu banco de dados na sua máquina, ganha um cache Redis, passa para a AWS com o banco de dados no Amazon RDS e, por fim, recebe os seus backups. Cada passo é um espaço de trabalho completo por si só, nos diretórios 1/ a 4/, e o build de cada um funciona tal como está.

Cada aggregate.yaml começa com um comentário de uma linha que nomeia o seu passo, e o mesmo vale para um release.yaml ou um manifest.yaml quando esse passo o altera. Comparar um arquivo com o do passo anterior mostra exatamente o que o passo acrescenta:

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

A aplicação é hub.aggrega.ai/tools/quickstart-web:1.1.0, sob a licença Apache-2.0. Ela lê a sua configuração somente do seu ambiente: PGHOST, PGPORT, PGUSER, PGPASSWORD e PGDATABASE para o PostgreSQL, e REDIS_HOST e REDIS_PORT para um cache, que ela usa apenas enquanto REDIS_HOST estiver definida. Ela escuta na porta 8080, e cada resposta sobre uma nota diz de onde a nota foi lida, no seu campo source, de modo que o cache é visível de fora.

Os blocos de saída desta página são copiados de uma execução real, conforme Lendo a saída nestas páginas.

Do que você precisa

  • A CLI aggrega, para cada passo.
  • Docker com Compose, para 1/ e 2/, que rodam na sua máquina.
  • Nada mais para 3/ e 4/: eles fazem o build de arquivos do Terraform e param. O primeiro build de cada um busca os módulos do RDS e do ElastiCache nos respectivos repositórios git. Planejar e aplicar esses arquivos é um ato separado, feito com a sua própria conta da AWS e as suas credenciais depois que os espaços reservados forem substituídos.

Executar com um único comando

Você pode executar o primeiro passo com um único comando ou pedir ao seu assistente de IA que o escreva e o construa para você.

Escolha uma senha para o banco de dados e exporte-a primeiro. No Linux ou macOS:

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

No Windows, no PowerShell:

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

A senha precisa ser exportada porque o Docker Compose a lê do seu shell, e o banco de dados mantém a primeira senha com que foi iniciado, então a segunda etapa precisa da mesma. O script se recusa a iniciar sem ela.

O script informa o que vai fazer e pergunta antes de prosseguir. Ele verifica se consegue encontrar aggrega, e se o Docker responde e tem o Compose. Ele grava o exemplo na pasta quickstart-web, ou usa essa pasta quando ela já existe. Em seguida, compila a primeira etapa e a inicia com o Docker Compose. O script termina exibindo a página do aplicativo, http://127.0.0.1:8080/.

Para executar outra etapa, indique-a: 2, 3 ou 4; as etapas 3 e 4 apenas compilam. No Linux ou no macOS, passe-a depois de sh -s -- e adicione ali --yes para prosseguir sem a pergunta:

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

No PowerShell, defina-o primeiro em QUICKSTART_STEP. Ele permanece definido nessa janela, para toda execução posterior, até que você o remova com Remove-Item Env:QUICKSTART_STEP:

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

Gerar o exemplo

Se você preferir compilá-lo e executá-lo passo a passo, escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example quickstart-web

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd quickstart-web

Build

Os comandos abaixo iniciam o primeiro passo, a partir do diretório deste exemplo. A senha é você quem escolhe: o Docker Compose a lê do seu shell quando o stack inicia, então nenhum arquivo a contém.

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

O build grava um único arquivo, dist/compose/docker-compose.yaml, e docker compose o inicia com o nome de projeto quickstart-web e retorna assim que os dois serviços estão no ar. Cada seçã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 este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do workspace ainda não contiver uma pasta `quickstart-web`, chame a ferramenta `scaffold` uma vez com `example` definido como `quickstart-web` e sem `dir`: ela escreve o exemplo em uma nova pasta `quickstart-web`, com um README e as pastas de etapa `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. Diga-me quais arquivos o build escreveu; eles ficam em `quickstart-web/1/dist/`.

Uma aplicação web e 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 o banco de dados em uma aresta, com os nomes que ela lê:

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

A senha chega às duas pontas por meio de uma vinculação 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 ela escuta, port: 8080, e published_port: 8080, a porta publicada para ela na sua máquina; sem published_port, nada é publicado ali. 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 do banco 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/ em um navegador na mesma máquina para ver a página do aplicativo. Ela mostra o banco de dados e o cache aos quais o aplicativo está conectado, e permite que você adicione uma nota e a leia. Cada leitura informa de onde veio, “from PostgreSQL” ou “from the cache”. Enquanto nenhum cache estiver conectado, a página exibe “No cache is wired to the app, so every read comes from PostgreSQL.”

Em um terminal, pergunte à aplicação a que ela está conectada, depois armazene uma nota e leia-a de volta:

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

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

O Manifest mapeia o novo tipo para compose/redis, e a Release posiciona o novo componente. Faça o build e inicie-o com o mesmo nome de projeto, com a mesma senha ainda 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

O Docker Compose deixa o banco de dados rodando, recria a aplicação com as suas duas novas variáveis e inicia o cache. O banco de dados foi criado com a senha que você exportou em 1/ e a mantém, então mantenha o mesmo valor neste passo. A nota armazenada em 1/ continua lá; leia-a duas vezes:

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

A primeira leitura vem do PostgreSQL e preenche o cache; a segunda vem do cache, que guarda uma nota por cinco minutos. Na página, ler uma nota duas vezes mostra “from PostgreSQL” e depois “from the cache”.

Quando terminar de usar o stack, remova-o, junto com os dados do banco de dados:

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

O mesmo banco de dados, gerenciado na AWS — 3/

Os mesmos três componentes, na AWS, por meio 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 as duas vinculações de senha: o RDS gera ele mesmo a senha do banco de dados, então nenhuma entrada do build traz uma. Na AWS, o RDS guarda a senha no AWS Secrets Manager, e a aplicação quickstart, que lê a sua senha apenas de PGPASSWORD, não consegue se autenticar até que você a forneça.

A Release nomeia, sob infra.overrides, o que você já executa na sua conta: o cluster ECS, as sub-redes e os grupos de segurança aos quais as tarefas se conectam, a função de execução com a qual o ECS baixa a imagem e grava os logs, e os grupos de sub-redes do RDS e do ElastiCache. Ela também define o engine_version do cache como 7.1, porque o ElastiCache executa o Redis OSS até a 7.1. Cada um desses valores é um espaço reservado: 123456789012 é o número de conta que a documentação da AWS usa em exemplos, e os IDs subnet-… e sg-…, os grupos de sub-redes, o cluster e a função representam recursos na sua própria conta. O build os aceita porque nunca os consulta; substitua-os antes de planejar.

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

A 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 agora são 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 que a instância e o cache sejam criados; o compilador canaliza os dois sem lê-los. Em uma cópia de dist/terraform, tofu init -backend=false carrega a raiz e os módulos incorporados e busca apenas os provedores, e tofu validate então imprime:

Success! The configuration is valid.

Adicionar backups — 4/

O RDS mantém os backups automatizados da instância por 7 dias, em uma janela que ele mesmo escolhe, quando nada diz o contrário — backup_retention_period = 7 acima. A Release vincula core/backup ao banco 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 próprio: o backup é uma configuração da instância, então a Recipe do banco de dados lê a vinculação e a grava no bloco do módulo da instância. O RDS faz um backup automatizado por dia, então o agendamento abre uma janela de 30 minutos nesse horário, em UTC. O Aggregate não muda.

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

A 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 = 7
backup_retention_period = 14
backup_window = "02:30-03:00"

Fazer o build não é implantar

3/ e 4/ gravam arquivos em dist/ e param. O build nunca executa o Terraform nem o OpenTofu, nunca se autentica na AWS e não consulta nenhum dos identificadores que as Releases nomeiam. Planejar e aplicar são passos que você executa sobre a saída, com as suas próprias credenciais, depois de substituir os espaços reservados.

Verificando cada passo

Em um checkout do repositório da documentação, que contém o helper de build compartilhado que uma cópia gravada por aggrega scaffold --example não traz, ./check.sh neste diretório faz o build dos quatro passos e verifica se cada um grava o que esta página mostra: os dois arquivos 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 configurações de backup. Ele imprime uma linha por passo e sai com código diferente de zero se algum passo divergir. dist/, .aggrega/ e os arquivos *.lock são gerados e não são commitados; eles são regenerados a partir dos arquivos que são.