Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Вебзастосунок із PostgreSQL, створений крок за кроком

Невеликий вебзастосунок, що зберігає нотатки в PostgreSQL, розвивається за чотири кроки: він починає з бази даних на вашій машині, отримує кеш Redis, переходить в AWS із базою даних на Amazon RDS і, нарешті, отримує резервні копії. Кожен крок — це повний самостійний робочий простір у каталогах від 1/ до 4/, і кожен збирається у своєму поточному вигляді.

Кожен aggregate.yaml починається з однорядкового коментаря, що називає його крок, і так само release.yaml чи manifest.yaml там, де цей крок їх змінює. Порівняння файлу з файлом попереднього кроку показує, що саме додає крок:

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

Застосунок — це hub.aggrega.ai/tools/quickstart-web:1.1.0 за ліцензією Apache-2.0. Він читає конфігурацію лише зі свого середовища: PGHOST, PGPORT, PGUSER, PGPASSWORD і PGDATABASE для PostgreSQL та REDIS_HOST і REDIS_PORT для кешу, який він використовує лише тоді, коли задано REDIS_HOST. Він слухає порт 8080, і кожна відповідь щодо нотатки повідомляє в полі source, звідки нотатку прочитано, тож кеш видно ззовні.

Блоки виводу на цій сторінці скопійовано з реального запуску, згідно з Читання виводу на цих сторінках.

Що вам знадобиться

  • CLI aggrega, для кожного кроку.
  • Docker із Compose, для 1/ і 2/, які працюють на вашій машині.
  • Для 3/ і 4/ більше нічого: вони збирають файли Terraform і зупиняються. Перша збірка кожного з них отримує модулі RDS і ElastiCache з їхніх git-репозиторіїв. Планування та застосування цих файлів — окрема дія, яку виконують із вашим власним обліковим записом AWS і обліковими даними після заміни заповнювачів.

Запуск однією командою

Перший крок можна запустити однією командою або доручити вашому ШІ-асистенту написати й зібрати його за вас.

Виберіть пароль для бази даних і спершу експортуйте його. У Linux або macOS:

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

У Windows, у PowerShell:

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

Пароль потрібно експортувати, оскільки Docker Compose читає його з вашої оболонки, а база даних зберігає перший пароль, з яким її було запущено, тож другий крок потребує того самого. Без нього скрипт відмовляється запускатися.

Скрипт повідомляє, що він зробить, і запитує, перш ніж продовжити. Він перевіряє, чи може знайти aggrega, а також чи відповідає Docker і чи має він Compose. Він записує приклад у теку quickstart-web або використовує цю теку, якщо вона вже існує. Потім він збирає перший крок і запускає його за допомогою Docker Compose. Наприкінці скрипт виводить сторінку застосунку, http://127.0.0.1:8080/.

Щоб запустити інший крок, назвіть його: 2, 3 або 4; кроки 3 і 4 лише виконують збирання. У Linux або macOS передайте його після sh -s -- і додайте там --yes, щоб продовжити без запитання:

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

У PowerShell спершу задайте його в QUICKSTART_STEP. Він залишається заданим у цьому вікні для кожного наступного запуску, доки ви не видалите його за допомогою Remove-Item Env:QUICKSTART_STEP:

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

Створення прикладу

Якщо ви волієте збирати й запускати його крок за кроком, запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example quickstart-web

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd quickstart-web

Збирання

Наведені нижче команди запускають перший крок із каталогу цього прикладу. Пароль ви обираєте самі: Docker Compose читає його з вашої оболонки під час запуску стека, тож жоден файл його не зберігає.

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

Збірка записує один файл, dist/compose/docker-compose.yaml, а docker compose запускає його під іменем проєкту quickstart-web і повертає керування, щойно обидві служби запущено. Кожен розділ нижче просуває на крок далі.

З ШІ-асистентом

ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.

Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `quickstart-web`, викличте один раз інструмент `scaffold` з `example`, що дорівнює `quickstart-web`, і без `dir`: він запише приклад у нову теку `quickstart-web` з README і теками кроків від `1` до `4`. Потім викличте інструмент `build` з `workspace_root`, що дорівнює `quickstart-web/1`, `release`, що дорівнює `release.yaml`, `auto_pull`, що дорівнює true, і `write`, що дорівнює true. Скажіть мені, які файли записала збірка; вони лежать у `quickstart-web/1/dist/`.

Вебзастосунок і його PostgreSQL — 1/

Aggregate оголошує два компоненти: web, типу core/compute/server, і db, типу core/datastore/postgres. Застосунок запитує базу даних на ребрі, під іменами, які він читає:

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

Пароль доходить до обох кінців через приєднання core/secret-value на кожному з них, джерелом якого є посилання на змінну Compose ${QUICKSTART_DB_PASSWORD}. Release вказує образ, закріплений дайджестом його багатоплатформного індексу, порт, на якому він слухає, port: 8080, і published_port: 8080 — порт, що публікується для нього на вашій машині; без published_port там нічого не публікується. Служба web у 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, ім’я служби бази даних у мережі Compose, а порт опубліковано лише на адресі зворотної петлі вашої машини.

Відкрийте http://127.0.0.1:8080/ у браузері на тій самій машині, щоб побачити сторінку застосунку. Вона називає базу даних і кеш, до яких під’єднано застосунок, і дає змогу додати нотатку та прочитати її. Кожне читання повідомляє, звідки воно надійшло, «from PostgreSQL» або «from the cache». Поки кеш ще не під’єднано, сторінка показує «No cache is wired to the app, so every read comes from PostgreSQL.»

У терміналі запитайте застосунок, до чого він під’єднаний, потім збережіть нотатку і прочитайте її:

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

Додавання кешу — 2/

Aggregate додає компонент cache типу core/datastore/redis і ще одне ребро в застосунку:

cache:
cache:
target: cache
inject:
env:
- in: REDIS_HOST
from: host
- in: REDIS_PORT
from: port

Manifest зіставляє новий тип із compose/redis, а Release розміщує новий компонент. Зберіть і запустіть його під тим самим іменем проєкту, з тим самим паролем, який досі експортовано:

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 залишає базу даних запущеною, заново створює застосунок із двома новими змінними і запускає кеш. Базу даних було створено з паролем, який ви експортували на кроці 1/, і вона його зберігає, тож для цього кроку збережіть те саме значення. Нотатка, збережена на кроці 1/, досі там; прочитайте її двічі:

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

Перше читання йде з PostgreSQL і заповнює кеш; друге йде з кешу, який зберігає нотатку п’ять хвилин. На сторінці дворазове читання нотатки показує «from PostgreSQL», а потім «from the cache».

Коли закінчите роботу зі стеком, видаліть його разом із даними бази даних:

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

Та сама база даних, керована в AWS — 3/

Ті самі три компоненти, в AWS, через Terraform. Manifest зіставляє сервер із terraform/server-ecs, службою Amazon ECS на Fargate; PostgreSQL — із terraform/postgres-rds-terraform-aws-modules, який містить вбудовану копію опублікованого модуля RDS проєкту terraform-aws-modules; а Redis — із terraform/redis-elasticache, який містить вбудовану копію його модуля ElastiCache. Ребра в сутності Aggregate не змінюються.

Із сутності Aggregate зникають два приєднання паролів: RDS сам генерує пароль бази даних, тож жодні вхідні дані збірки не містять пароля. В AWS RDS зберігає пароль в AWS Secrets Manager, а застосунок quickstart, який читає свій пароль лише з PGPASSWORD, не може ввійти, доки ви його не надасте.

Release вказує в infra.overrides те, що ви вже запускаєте у своєму обліковому записі: кластер ECS, підмережі та групи безпеки, до яких під’єднуються завдання, роль виконання, з якою ECS завантажує образ і записує журнали, а також групи підмереж RDS і ElastiCache. Він також встановлює engine_version кешу на 7.1, оскільки ElastiCache запускає Redis OSS до версії 7.1. Кожне з цих значень є заповнювачем: 123456789012 — це номер облікового запису, який документація AWS використовує в прикладах, а ідентифікатори subnet-… і sg-…, групи підмереж, кластер і роль позначають ресурси у вашому власному обліковому записі. Збірка їх приймає, бо ніколи їх не перевіряє; замініть їх перед плануванням.

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

Коренева конфігурація, 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"]
}

Застосунок отримує ті самі імена, що й у Compose. PGHOST і REDIS_HOST тепер є посиланнями на власні виходи модулів RDS і ElastiCache, які Terraform розв’язує під час застосування конфігурації, бо жодна з цих адрес не існує до створення екземпляра й кешу; компілятор передає обидва далі, не читаючи їх. На копії dist/terraform команда tofu init -backend=false завантажує кореневий модуль і вбудовані модулі та отримує лише провайдери, а потім tofu validate виводить:

Success! The configuration is valid.

Додавання резервних копій — 4/

RDS зберігає автоматичні резервні копії екземпляра 7 днів, у вікні, яке обирає сам, якщо ніщо не вказує інше, — backup_retention_period = 7 вище. Release приєднує core/backup до бази даних:

db:
features:
backup:
type: core/backup
infra:
retention_days: 14
schedule: "30 2 * * *"

а Manifest прив’язує сутність Feature до terraform/backup-native, який сам нічого не рендерить: резервне копіювання — це налаштування екземпляра, тож Recipe бази даних читає приєднання і записує його в блок модуля екземпляра. RDS робить одну автоматичну резервну копію на день, тож розклад відкриває в цей час 30-хвилинне вікно, в UTC. Aggregate не змінюється.

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

Коренева конфігурація відрізняється від конфігурації кроку 3/ лише блоком модуля db, і tofu validate на ній так само виводить Success! The configuration is valid.:

backup_retention_period = 7
backup_retention_period = 14
backup_window = "02:30-03:00"

Збирання — це не розгортання

3/ і 4/ записують файли в dist/ і зупиняються. Збірка ніколи не запускає Terraform чи OpenTofu, ніколи не автентифікується в AWS і не перевіряє жодного з ідентифікаторів, які вказують Releases. Планування та застосування — це кроки, які ви виконуєте з результатом, зі своїми власними обліковими даними, після заміни заповнювачів.

Перевірка кожного кроку

У робочій копії репозиторію документації, яка містить спільний допоміжний скрипт збирання, якого немає в копії, записаній aggrega scaffold --example, ./check.sh у цьому каталозі збирає чотири кроки та перевіряє, що кожен записує те, що показано на цій сторінці: два файли Compose з їхніми службами та змінними і дві кореневі конфігурації Terraform з їхніми блоками модулів, посиланнями та налаштуваннями резервного копіювання. Він виводить один рядок на крок і завершується з ненульовим кодом, якщо будь-який крок відрізняється. dist/, .aggrega/ і файли *.lock генеруються і не комітяться; вони заново генеруються з файлів, які закомічено.