Aplikacja webowa z PostgreSQL, budowana krok po kroku
Mała aplikacja webowa przechowująca notatki w PostgreSQL, rozbudowywana w czterech krokach: zaczyna z bazą danych na lokalnej maszynie, zyskuje pamięć podręczną Redis, przenosi się do AWS z bazą danych w Amazon RDS, a na koniec otrzymuje kopie zapasowe. Każdy krok to kompletna, samodzielna przestrzeń robocza w katalogach od 1/ do 4/ i każdy daje się zbudować w obecnej postaci.
Każdy plik aggregate.yaml zaczyna się od jednowierszowego komentarza nazywającego jego krok; tak samo release.yaml lub manifest.yaml tam, gdzie dany krok je zmienia. Porównanie pliku z jego odpowiednikiem z poprzedniego kroku pokazuje dokładnie, co dany krok dodaje:
diff 1/aggregate.yaml 2/aggregate.yamlAplikacją jest hub.aggrega.ai/tools/quickstart-web:1.1.0, na licencji Apache-2.0. Odczytuje konfigurację wyłącznie ze swojego środowiska: PGHOST, PGPORT, PGUSER, PGPASSWORD i PGDATABASE dla PostgreSQL oraz REDIS_HOST i REDIS_PORT dla pamięci podręcznej, której używa tylko wtedy, gdy ustawiona jest REDIS_HOST. Nasłuchuje na porcie 8080, a każda odpowiedź dotycząca notatki podaje w polu source, skąd notatka została odczytana, dzięki czemu pamięć podręczna jest widoczna z zewnątrz.
Bloki wyjścia na tej stronie są skopiowane z rzeczywistego uruchomienia, zgodnie z Odczytywanie wyjścia na tych stronach.
Czego potrzeba
- CLI
aggrega, w każdym kroku. - Docker z Compose, dla
1/i2/, które działają na lokalnej maszynie. - Nic więcej dla
3/i4/: budują pliki Terraform i się zatrzymują. Pierwsza kompilacja każdego z nich pobiera moduły RDS i ElastiCache z ich repozytoriów git. Planowanie i stosowanie tych plików to osobna czynność, wykonywana własnym kontem AWS i poświadczeniami po zastąpieniu symboli zastępczych.
Uruchamianie jednym poleceniem
Pierwszy krok można uruchomić jednym poleceniem albo zlecić asystentowi AI jego napisanie i zbudowanie.
Należy wybrać hasło do bazy danych i najpierw je wyeksportować. W systemie Linux lub macOS:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shW systemie Windows, w PowerShell:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexHasło trzeba wyeksportować, ponieważ Docker Compose odczytuje je z powłoki, a baza danych zachowuje pierwsze hasło, z którym została uruchomiona, więc drugi krok wymaga tego samego. Bez niego skrypt odmawia uruchomienia.
Skrypt informuje, co zrobi, i pyta przed kontynuowaniem. Sprawdza, czy może znaleźć aggrega oraz czy Docker odpowiada i ma Compose. Zapisuje przykład w folderze quickstart-web lub używa tego folderu, jeśli już istnieje. Następnie buduje pierwszy krok i uruchamia go za pomocą Docker Compose. Na koniec skrypt wypisuje stronę aplikacji, http://127.0.0.1:8080/.
Aby uruchomić inny krok, należy go wskazać: 2, 3 lub 4; kroki 3 i 4 tylko budują. W systemie Linux lub macOS podaje się go po sh -s --, a dodanie tam --yes pozwala kontynuować bez pytania:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2W PowerShell należy najpierw ustawić go w QUICKSTART_STEP. Pozostaje ustawiony w tym oknie, dla każdego kolejnego uruchomienia, dopóki nie zostanie usunięty poleceniem Remove-Item Env:QUICKSTART_STEP:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexGenerowanie przykładu
Jeśli przykład ma być budowany i uruchamiany krok po kroku, należy zapisać go w nowym folderze nazwanym tak jak on:
aggrega scaffold --example quickstart-webNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd quickstart-webKompilacja
Poniższe polecenia uruchamiają pierwszy krok z katalogu tego przykładu. Hasło należy wybrać samodzielnie: Docker Compose odczytuje je z powłoki przy starcie stosu, więc żaden plik go nie przechowuje.
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 browserKompilacja zapisuje jeden plik, dist/compose/docker-compose.yaml, a docker compose uruchamia go pod nazwą projektu quickstart-web i kończy działanie, gdy obie usługi będą działać. Każda z poniższych sekcji przechodzi o jeden krok dalej.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i sam nie twórz żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `quickstart-web`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `quickstart-web` i bez `dir`: zapisze ono przykład do nowego folderu `quickstart-web`, z plikiem README i folderami kroków od `1` do `4`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `quickstart-web/1`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisała kompilacja; znajdują się w `quickstart-web/1/dist/`.Aplikacja webowa i jej PostgreSQL — 1/
Aggregate deklaruje dwa komponenty: web, typu core/compute/server, oraz db, typu core/datastore/postgres. Aplikacja żąda bazy danych na krawędzi, pod nazwami, które odczytuje:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseHasło dociera do obu końców przez dołączenie core/secret-value na każdym z nich, którego źródłem jest odwołanie do zmiennej Compose ${QUICKSTART_DB_PASSWORD}. Release wskazuje obraz, przypięty skrótem jego wieloplatformowego indeksu, port, na którym nasłuchuje, port: 8080, oraz published_port: 8080, czyli port publikowany dla niego na maszynie; bez published_port nic nie jest tam publikowane. Usługa web w 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 to db, nazwa usługi bazy danych w sieci Compose, a port jest publikowany wyłącznie na adresie pętli zwrotnej lokalnej maszyny.
Należy otworzyć http://127.0.0.1:8080/ w przeglądarce na tej samej maszynie, aby zobaczyć stronę aplikacji. Strona podaje bazę danych i pamięć podręczną, z którymi aplikacja jest połączona, oraz pozwala dodać notatkę i ją odczytać. Każdy odczyt podaje, skąd pochodzi, „from PostgreSQL” lub „from the cache”. Dopóki żadna pamięć podręczna nie jest podłączona, strona wyświetla „No cache is wired to the app, so every read comes from PostgreSQL.”
W terminalu należy zapytać aplikację, z czym jest połączona, a następnie zapisać notatkę i odczytać ją z powrotem:
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"}Dodanie pamięci podręcznej — 2/
Aggregate dodaje komponent cache typu core/datastore/redis oraz jeszcze jedną krawędź w aplikacji:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portManifest mapuje nowy typ na compose/redis, a Release rozmieszcza nowy komponent. Należy go zbudować i uruchomić pod tą samą nazwą projektu, przy wciąż wyeksportowanym tym samym haśle:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose pozostawia działającą bazę danych, odtwarza aplikację z jej dwiema nowymi zmiennymi i uruchamia pamięć podręczną. Baza danych została utworzona z hasłem wyeksportowanym w 1/ i je zachowuje, więc w tym kroku należy zachować tę samą wartość. Notatka zapisana w 1/ nadal tam jest; należy odczytać ją dwukrotnie:
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"}Pierwszy odczyt pochodzi z PostgreSQL i wypełnia pamięć podręczną; drugi pochodzi z pamięci podręcznej, która przechowuje notatkę przez pięć minut. Na stronie dwukrotny odczyt notatki pokazuje „from PostgreSQL”, a potem „from the cache”.
Po zakończeniu pracy ze stosem należy go usunąć razem z danymi bazy danych:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -vTa sama baza danych, zarządzana w AWS — 3/
Te same trzy komponenty, w AWS, przez Terraform. Manifest mapuje serwer na terraform/server-ecs, usługę Amazon ECS na Fargate; PostgreSQL na terraform/postgres-rds-terraform-aws-modules, który zawiera dołączoną kopię opublikowanego modułu RDS projektu terraform-aws-modules; a Redis na terraform/redis-elasticache, który zawiera dołączoną kopię jego modułu ElastiCache. Krawędzie w encji Aggregate się nie zmieniają.
Z encji Aggregate znikają dwa dołączenia haseł: RDS sam generuje hasło bazy danych, więc żadne wejście kompilacji go nie zawiera. W AWS RDS przechowuje hasło w AWS Secrets Manager, a aplikacja quickstart, która odczytuje hasło wyłącznie z PGPASSWORD, nie może się zalogować, dopóki hasło nie zostanie jej dostarczone.
Release wskazuje w infra.overrides to, co już działa na koncie: klaster ECS, podsieci i grupy zabezpieczeń, do których podłączają się zadania, rolę wykonawczą, za pomocą której ECS pobiera obraz i zapisuje logi, oraz grupy podsieci RDS i ElastiCache. Ustawia też engine_version pamięci podręcznej na 7.1, ponieważ ElastiCache obsługuje Redis OSS do wersji 7.1. Każda z tych wartości jest symbolem zastępczym: 123456789012 to numer konta używany w przykładach w dokumentacji AWS, a identyfikatory subnet-… i sg-…, grupy podsieci, klaster i rola oznaczają zasoby na własnym koncie. Kompilacja je akceptuje, ponieważ nigdy ich nie sprawdza; należy je zastąpić przed planowaniem.
cd ../3aggrega build --release release.yaml --auto-pullKonfiguracja główna, 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"]}Aplikacja otrzymuje te same nazwy co w Compose. PGHOST i REDIS_HOST są teraz odwołaniami do własnych wyjść modułów RDS i ElastiCache, które Terraform rozwiązuje podczas stosowania konfiguracji, ponieważ żaden z tych adresów nie istnieje przed utworzeniem instancji i pamięci podręcznej; kompilator przekazuje oba dalej, nie odczytując ich. Na kopii dist/terraform polecenie tofu init -backend=false ładuje moduł główny i dołączone moduły oraz pobiera wyłącznie dostawców, a następnie tofu validate wypisuje:
Success! The configuration is valid.Dodanie kopii zapasowych — 4/
RDS przechowuje automatyczne kopie zapasowe instancji przez 7 dni, w wybranym przez siebie oknie czasowym, jeśli nic nie stanowi inaczej — backup_retention_period = 7 powyżej. Release dołącza core/backup do bazy danych:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"a Manifest wiąże encję Feature z terraform/backup-native, który sam niczego nie renderuje: kopia zapasowa jest ustawieniem instancji, więc Recipe bazy danych odczytuje dołączenie i zapisuje je w bloku modułu instancji. RDS wykonuje jedną automatyczną kopię zapasową dziennie, więc harmonogram otwiera o tej godzinie 30-minutowe okno, w UTC. Aggregate się nie zmienia.
cd ../4aggrega build --release release.yaml --auto-pullKonfiguracja główna różni się od tej z 3/ wyłącznie blokiem modułu db, a tofu validate uruchomione na niej również wypisuje Success! The configuration is valid.:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Budowanie to nie wdrażanie
3/ i 4/ zapisują pliki w dist/ i się zatrzymują. Kompilacja nigdy nie uruchamia Terraform ani OpenTofu, nigdy nie uwierzytelnia się w AWS i nie sprawdza żadnego z identyfikatorów, które wskazują Releases. Planowanie i stosowanie to kroki wykonywane na wyniku, z własnymi poświadczeniami, po zastąpieniu symboli zastępczych.
Sprawdzanie każdego kroku
W kopii roboczej repozytorium dokumentacji, która zawiera wspólny skrypt pomocniczy budowania, którego nie ma kopia zapisana przez aggrega scaffold --example, ./check.sh w tym katalogu buduje cztery kroki i sprawdza, czy każdy zapisuje to, co pokazuje ta strona: dwa pliki Compose z ich usługami i zmiennymi oraz dwie główne konfiguracje Terraform z ich blokami modułów, odwołaniami i ustawieniami kopii zapasowych. Wypisuje jeden wiersz na krok i kończy działanie z kodem niezerowym, jeśli którykolwiek krok się różni. dist/, .aggrega/ i pliki *.lock są generowane i nie są commitowane; generują się ponownie z plików, które są.