Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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: 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:

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. 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/ e 2/, que são executados na sua máquina.
  • Nada mais para 3/ e 4/: 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:

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

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

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

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

Gerar o exemplo

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

Terminal window
aggrega scaffold --example quickstart-web

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd quickstart-web

Compilaçã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.

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

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

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

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

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

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

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

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

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

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

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"

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.