Вебзастосунок із PostgreSQL, створений крок за кроком
Невеликий вебзастосунок, що зберігає нотатки в PostgreSQL, розвивається за чотири кроки: він починає з бази даних на вашій машині, отримує кеш Redis, переходить в AWS із базою даних на Amazon RDS і, нарешті, отримує резервні копії. Кожен крок — це повний самостійний робочий простір у каталогах від 1/ до 4/, і кожен збирається у своєму поточному вигляді.
Кожен aggregate.yaml починається з однорядкового коментаря, що називає його крок, і так само release.yaml чи manifest.yaml там, де цей крок їх змінює. Порівняння файлу з файлом попереднього кроку показує, що саме додає крок:
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:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shУ Windows, у PowerShell:
$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, щоб продовжити без запитання:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2У PowerShell спершу задайте його в QUICKSTART_STEP. Він залишається заданим у цьому вікні для кожного наступного запуску, доки ви не видалите його за допомогою Remove-Item Env:QUICKSTART_STEP:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexСтворення прикладу
Якщо ви волієте збирати й запускати його крок за кроком, запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example quickstart-webПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd quickstart-webЗбирання
Наведені нижче команди запускають перший крок із каталогу цього прикладу. Пароль ви обираєте самі: Docker Compose читає його з вашої оболонки під час запуску стека, тож жоден файл його не зберігає.
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 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.»
У терміналі запитайте застосунок, до чого він під’єднаний, потім збережіть нотатку і прочитайте її:
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"}Додавання кешу — 2/
Aggregate додає компонент cache типу core/datastore/redis і ще одне ребро в застосунку:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portManifest зіставляє новий тип із compose/redis, а Release розміщує новий компонент. Зберіть і запустіть його під тим самим іменем проєкту, з тим самим паролем, який досі експортовано:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose залишає базу даних запущеною, заново створює застосунок із двома новими змінними і запускає кеш. Базу даних було створено з паролем, який ви експортували на кроці 1/, і вона його зберігає, тож для цього кроку збережіть те саме значення. Нотатка, збережена на кроці 1/, досі там; прочитайте її двічі:
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"}Перше читання йде з PostgreSQL і заповнює кеш; друге йде з кешу, який зберігає нотатку п’ять хвилин. На сторінці дворазове читання нотатки показує «from PostgreSQL», а потім «from the cache».
Коли закінчите роботу зі стеком, видаліть його разом із даними бази даних:
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-…, групи підмереж, кластер і роль позначають ресурси у вашому власному обліковому записі. Збірка їх приймає, бо ніколи їх не перевіряє; замініть їх перед плануванням.
cd ../3aggrega 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 не змінюється.
cd ../4aggrega build --release release.yaml --auto-pullКоренева конфігурація відрізняється від конфігурації кроку 3/ лише блоком модуля db, і tofu validate на ній так само виводить Success! The configuration is valid.:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Збирання — це не розгортання
3/ і 4/ записують файли в dist/ і зупиняються. Збірка ніколи не запускає Terraform чи OpenTofu, ніколи не автентифікується в AWS і не перевіряє жодного з ідентифікаторів, які вказують Releases. Планування та застосування — це кроки, які ви виконуєте з результатом, зі своїми власними обліковими даними, після заміни заповнювачів.
Перевірка кожного кроку
У робочій копії репозиторію документації, яка містить спільний допоміжний скрипт збирання, якого немає в копії, записаній aggrega scaffold --example, ./check.sh у цьому каталозі збирає чотири кроки та перевіряє, що кожен записує те, що показано на цій сторінці: два файли Compose з їхніми службами та змінними і дві кореневі конфігурації Terraform з їхніми блоками модулів, посиланнями та налаштуваннями резервного копіювання. Він виводить один рядок на крок і завершується з ненульовим кодом, якщо будь-який крок відрізняється. dist/, .aggrega/ і файли *.lock генеруються і не комітяться; вони заново генеруються з файлів, які закомічено.