İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

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:

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

Uygulama 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 aggrega CLI.
  • Sizin makinenizde çalışan 1/ ve 2/ için Compose ile birlikte Docker.
  • 3/ ve 4/ 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:

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

Windows’ta, PowerShell’de:

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

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

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

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

Terminal window
$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:

Terminal window
aggrega scaffold --example quickstart-web

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd quickstart-web

Derleme

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Kö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 = 7
backup_retention_period = 14
backup_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.