PostgreSQL kullanan bir web uygulaması, adım adım oluşturuluyor
Notları PostgreSQL’de tutan küçük bir web uygulaması, dört adımda büyütülür: veritabanı sizin makinenizdeyken başlar, bir Redis önbelleği kazanır, veritabanı Amazon RDS’te olacak şekilde AWS’ye taşınır ve son olarak yedeklerine kavuşur. Her adım, 1/ ile 4/ arasındaki dizinlerde kendi başına eksiksiz bir çalışma alanıdır ve her biri olduğu haliyle derlenir.
Her aggregate.yaml, adımını belirten tek satırlık bir yorumla başlar; o adımın değiştirdiği yerlerde release.yaml veya manifest.yaml dosyası da öyle. Bir dosyayı önceki adımdakiyle karşılaştırmak, adımın tam olarak neyi eklediğini gösterir:
diff 1/aggregate.yaml 2/aggregate.yamlUygulama olarak Apache-2.0 lisanslı hub.aggrega.ai/tools/quickstart-web:1.1.0 kullanılır. Yapılandırmasını yalnızca ortamından okur: PostgreSQL için PGHOST, PGPORT, PGUSER, PGPASSWORD ve PGDATABASE, önbellek için ise REDIS_HOST ve REDIS_PORT; önbelleği yalnızca REDIS_HOST ayarlıyken kullanır. 8080 portunu dinler ve bir notla ilgili her yanıt, notun nereden okunduğunu source alanında belirtir; böylece önbellek dışarıdan görünür olur.
Bu sayfadaki çıktı blokları, Bu sayfalardaki çıktıyı okumak uyarınca gerçek bir çalıştırmadan kopyalanmıştır.
Gerekenler
- Her adım için
aggregaCLI. - Sizin makinenizde çalışan
1/ve2/için Compose ile birlikte Docker. 3/ve4/için başka bir şey gerekmez: bunlar Terraform dosyaları derler ve durur. Her birinin ilk derlemesi RDS ve ElastiCache modüllerini git depolarından getirir. Bu dosyaları planlamak ve uygulamak ayrı bir iştir; yer tutucular değiştirildikten sonra kendi AWS hesabınız ve kimlik bilgilerinizle yapılır.
Tek komutla çalıştırma
İlk adımı tek bir komutla çalıştırabilir ya da yapay zekâ asistanınıza sizin için yazdırıp derletebilirsiniz.
Veritabanı için bir parola seçin ve önce onu dışa aktarın. Linux veya macOS’te:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shWindows’ta, PowerShell’de:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexParolanın dışa aktarılması gerekir, çünkü Docker Compose onu kabuğunuzdan okur ve veritabanı ilk başlatıldığı parolayı korur; bu yüzden ikinci adım da aynı parolayı gerektirir. Betik, parola olmadan başlamayı reddeder.
Betik ne yapacağını söyler ve devam etmeden önce sorar. aggrega’yı bulabildiğini, Docker’ın yanıt verdiğini ve Compose’a sahip olduğunu denetler. Örneği quickstart-web klasörüne yazar ya da bu klasör zaten varsa onu kullanır. Ardından ilk adımı derler ve Docker Compose ile başlatır. Betik, uygulamanın sayfasını, http://127.0.0.1:8080/, yazdırarak sona erer.
Başka bir adımı çalıştırmak için onu belirtin: 2, 3 veya 4; 3. ve 4. adımlar yalnızca derleme yapar. Linux veya macOS’ta onu sh -s -- sonrasında verin ve soru sorulmadan devam etmek için oraya --yes ekleyin:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2PowerShell’de önce adımı QUICKSTART_STEP içinde ayarlayın. Remove-Item Env:QUICKSTART_STEP ile kaldırana kadar o pencerede, sonraki her çalıştırma için ayarlı kalır:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexÖrneği oluşturun
Örneği adım adım derleyip çalıştırmayı tercih ederseniz, örneği adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example quickstart-webArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd quickstart-webDerleme
Aşağıdaki komutlar, bu örneğin dizininden ilk adımı başlatır. Parolayı siz seçersiniz: Docker Compose onu yığın başlarken kabuğunuzdan okur, bu yüzden hiçbir dosya onu tutmaz.
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 browserDerleme tek bir dosya yazar, dist/compose/docker-compose.yaml; docker compose onu quickstart-web proje adıyla başlatır ve her iki servis de ayağa kalktığında geri döner. Aşağıdaki her bölüm bir adım daha ilerler.
Bir yapay zekâ asistanıyla
Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Çalışma alanı klasöründe henüz bir `quickstart-web` klasörü yoksa `scaffold` aracını, `example` değeri `quickstart-web` olarak ayarlanmış ve `dir` verilmeden bir kez çağırın: araç örneği, bir README ve `1` ile `4` arasındaki adım klasörleriyle birlikte yeni bir `quickstart-web` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `quickstart-web/1`, `release` değeri `release.yaml`, `auto_pull` değeri true ve `write` değeri true olarak ayarlanmış şekilde çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; bunlar `quickstart-web/1/dist/` altındadır.Bir web uygulaması ve PostgreSQL’i — 1/
Aggregate iki bileşen bildirir: web, core/compute/server türünde, ve db, core/datastore/postgres türünde. Uygulama, veritabanını bir kenar üzerinden, okuduğu adlar altında ister:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseParola her iki uca, her birindeki bir core/secret-value eklemesi aracılığıyla ulaşır; bu eklemenin kaynağı Compose değişken başvurusu ${QUICKSTART_DB_PASSWORD} olur. Release, çok platformlu dizininin özetiyle sabitlenmiş imajı, dinlediği portu, yani port: 8080 değerini, ve makinenizde onun için yayımlanan port olan published_port: 8080 değerini belirtir; published_port olmadan orada hiçbir şey yayımlanmaz. web servisi, dist/compose/docker-compose.yaml içinde:
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 değeri db olur, yani veritabanının Compose ağındaki servis adı; port ise yalnızca makinenizin geri döngü adresinde yayımlanır.
Aynı makinede bir tarayıcıda http://127.0.0.1:8080/ adresini açarak uygulamanın sayfasını görün. Sayfa, uygulamanın bağlı olduğu veritabanını ve önbelleği adlandırır, ayrıca bir not eklemenize ve onu okumanıza olanak tanır. Her okuma nereden geldiğini söyler, “from PostgreSQL” veya “from the cache”. Henüz bağlı bir önbellek yokken sayfada “No cache is wired to the app, so every read comes from PostgreSQL.” yazar.
Bir terminalden uygulamaya neye bağlı olduğunu sorun, ardından bir not kaydedin ve geri okuyun:
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"}Önbellek ekleyin — 2/
Aggregate bir cache bileşeni (türü core/datastore/redis) ve uygulamada bir kenar daha ekler:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portManifest yeni türü compose/redis ile eşler ve Release yeni bileşeni yerleştirir. Aynı parola hâlâ dışa aktarılmış durumdayken aynı proje adıyla derleyip başlatın:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose veritabanını çalışır halde bırakır, uygulamayı iki yeni değişkeniyle yeniden oluşturur ve önbelleği başlatır. Veritabanı, 1/ adımında dışa aktardığınız parolayla oluşturuldu ve onu korur; bu yüzden bu adım için aynı değeri koruyun. 1/ adımında kaydedilen not hâlâ orada; onu iki kez okuyun:
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"}İlk okuma PostgreSQL’den gelir ve önbelleği doldurur; ikincisi, bir notu beş dakika tutan önbellekten gelir. Sayfada bir notu iki kez okumak önce “from PostgreSQL”, ardından “from the cache” gösterir.
Yığınla işiniz bittiğinde, veritabanının verileriyle birlikte onu kaldırın:
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -vAynı veritabanı, AWS’de yönetilen hizmet olarak — 3/
Aynı üç bileşen, Terraform aracılığıyla AWS üzerinde. Manifest sunucuyu, Fargate üzerinde bir Amazon ECS servisi olan terraform/server-ecs ile; PostgreSQL’i, terraform-aws-modules projesinin yayımlanmış RDS modülünü kendi içine alan terraform/postgres-rds-terraform-aws-modules ile; Redis’i ise o projenin ElastiCache modülünü kendi içine alan terraform/redis-elasticache ile eşler. Aggregate’teki kenarlar değişmez.
Aggregate’ten çıkarılan, iki parola eklemesidir: RDS veritabanının parolasını kendisi üretir, bu yüzden hiçbir derleme girdisi parola taşımaz. AWS’de RDS parolayı AWS Secrets Manager’da saklar ve parolasını yalnızca PGPASSWORD değişkeninden okuyan quickstart uygulaması, siz parolayı sağlayana kadar oturum açamaz.
Release, infra.overrides altında hesabınızda zaten çalıştırdığınız şeyleri belirtir: ECS kümesi, görevlerin bağlandığı alt ağlar ve güvenlik grupları, ECS’nin imajı çekmek ve günlük yazmak için kullandığı yürütme rolü ve RDS ile ElastiCache alt ağ grupları. Ayrıca önbelleğin engine_version değerini 7.1 olarak ayarlar, çünkü ElastiCache Redis OSS’yi 7.1 sürümüne kadar çalıştırır. Bu değerlerin her biri bir yer tutucudur: 123456789012, AWS belgelerinin örneklerde kullandığı hesap numarasıdır; subnet-… ve sg-… kimlikleri, alt ağ grupları, küme ve rol ise kendi hesabınızdaki kaynakları temsil eder. Derleme bunları hiçbir zaman sorgulamadığı için kabul eder; planlamadan önce bunları değiştirin.
cd ../3aggrega build --release release.yaml --auto-pullKök yapılandırma, 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"]}Uygulama, Compose’dakiyle aynı adları alır. PGHOST ve REDIS_HOST artık RDS ve ElastiCache modüllerinin kendi çıktılarına yapılan başvurulardır; Terraform bunları yapılandırmayı uygularken çözümler, çünkü veritabanı örneği ve önbellek oluşturulmadan önce bu adreslerin hiçbiri mevcut değildir; derleyici ikisini de okumadan olduğu gibi aktarır. dist/terraform dizininin bir kopyası üzerinde tofu init -backend=false, kök modülü ve içe alınmış modülleri yükler ve yalnızca sağlayıcıları getirir; ardından tofu validate şunu yazdırır:
Success! The configuration is valid.Yedekler ekleyin — 4/
Aksi belirtilmedikçe RDS, veritabanı örneğinin otomatik yedeklerini kendi seçtiği bir zaman aralığında 7 gün boyunca tutar — yukarıdaki backup_retention_period = 7. Release, veritabanına core/backup ekler:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"ve Manifest, Feature’ı terraform/backup-native ile bağlar; bu, kendi başına hiçbir şey oluşturmaz: yedekleme, veritabanı örneğinin bir ayarıdır, bu yüzden veritabanı Recipe’si eklemeyi okur ve onu veritabanı örneğinin modül bloğuna yazar. RDS günde bir otomatik yedek alır, bu yüzden zamanlama o saatte, UTC olarak, 30 dakikalık bir zaman aralığı açar. Aggregate değişmez.
cd ../4aggrega build --release release.yaml --auto-pullKök yapılandırma, 3/ adımındakinden yalnızca db modül bloğunda farklıdır ve üzerinde çalıştırılan tofu validate de Success! The configuration is valid. yazdırır:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"Derlemek dağıtmak değildir
3/ ve 4/, dosyaları dist/ altına yazar ve durur. Derleme hiçbir zaman Terraform veya OpenTofu çalıştırmaz, AWS’ye karşı kimlik doğrulaması yapmaz ve Releases içinde belirtilen tanımlayıcıların hiçbirini sorgulamaz. Planlama ve uygulama, yer tutucuları değiştirdikten sonra çıktı üzerinde kendi kimlik bilgilerinizle attığınız adımlardır.
Her adımı denetleme
Belgelendirme deposunun bir çalışma kopyasında — aggrega scaffold --example tarafından yazılan bir kopyanın içermediği ortak derleme yardımcı betiğini barındırır — bu dizindeki ./check.sh, dört adımı derler ve her birinin bu sayfada gösterilenleri yazdığını denetler: servisleri ve değişkenleriyle iki Compose dosyası ile modül blokları, başvuruları ve yedekleme ayarlarıyla iki Terraform kök yapılandırması. Adım başına bir satır yazdırır ve herhangi bir adım farklıysa sıfırdan farklı bir kodla çıkar. dist/, .aggrega/ ve *.lock dosyaları üretilir ve commit edilmez; commit edilen dosyalardan yeniden üretilirler.