Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Aplikasi web dengan PostgreSQL, dibangun selangkah demi selangkah

Sebuah aplikasi web kecil yang menyimpan catatan di PostgreSQL, dikembangkan dalam empat langkah: aplikasi ini dimulai dengan database di mesin Anda, lalu mendapatkan cache Redis, kemudian pindah ke AWS dengan database di Amazon RDS, dan akhirnya mendapatkan pencadangannya. Setiap langkah adalah ruang kerja lengkap tersendiri, di direktori 1/ hingga 4/, dan masing-masing dapat di-build apa adanya.

Setiap aggregate.yaml diawali dengan komentar satu baris yang menyebutkan langkahnya, begitu pula release.yaml atau manifest.yaml di langkah yang mengubahnya. Membandingkan sebuah file dengan file dari langkah sebelumnya menunjukkan dengan tepat apa yang ditambahkan langkah tersebut:

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

Aplikasinya adalah hub.aggrega.ai/tools/quickstart-web:1.1.0, di bawah lisensi Apache-2.0. Aplikasi ini membaca konfigurasinya hanya dari lingkungannya: PGHOST, PGPORT, PGUSER, PGPASSWORD, dan PGDATABASE untuk PostgreSQL, serta REDIS_HOST dan REDIS_PORT untuk cache, yang hanya digunakannya selama REDIS_HOST disetel. Aplikasi ini mendengarkan di port 8080, dan setiap jawaban tentang sebuah catatan menyebutkan dari mana catatan itu dibaca, pada field source, sehingga cache terlihat dari luar.

Blok output di halaman ini disalin dari eksekusi nyata, sesuai dengan Membaca output di halaman-halaman ini.

Yang Anda perlukan

  • CLI aggrega, untuk setiap langkah.
  • Docker dengan Compose, untuk 1/ dan 2/, yang berjalan di mesin Anda.
  • Tidak ada lagi untuk 3/ dan 4/: keduanya mem-build file Terraform lalu berhenti. Build pertama masing-masing mengambil modul RDS dan ElastiCache dari repositori git-nya. Merencanakan dan menerapkan file tersebut adalah tindakan terpisah, yang dilakukan dengan akun dan kredensial AWS Anda sendiri setelah placeholder diganti.

Menjalankannya dengan satu perintah

Anda dapat menjalankan langkah pertama dengan satu perintah, atau meminta asisten AI Anda menulis dan mem-build-nya untuk Anda.

Pilih kata sandi untuk database dan ekspor terlebih dahulu. Di Linux atau macOS:

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

Di Windows, di PowerShell:

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

Kata sandi harus diekspor karena Docker Compose membacanya dari shell Anda, dan database menyimpan kata sandi pertama yang digunakan saat dijalankan, sehingga langkah kedua memerlukan kata sandi yang sama. Skrip menolak untuk mulai tanpanya.

Skrip memberi tahu apa yang akan dilakukannya dan bertanya sebelum melanjutkan. Skrip memeriksa bahwa ia dapat menemukan aggrega, serta bahwa Docker merespons dan memiliki Compose. Skrip menulis contoh ke folder quickstart-web, atau menggunakan folder itu jika sudah ada. Kemudian skrip membangun langkah pertama dan menjalankannya dengan Docker Compose. Skrip diakhiri dengan mencetak halaman aplikasi, http://127.0.0.1:8080/.

Untuk menjalankan langkah lain, sebutkan langkahnya: 2, 3, atau 4; langkah 3 dan 4 hanya membangun. Di Linux atau macOS, berikan setelah sh -s --, dan tambahkan --yes di sana untuk melanjutkan tanpa pertanyaan tersebut:

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

Di PowerShell, atur dulu di QUICKSTART_STEP. Nilai itu tetap teratur di jendela tersebut, untuk setiap eksekusi berikutnya, sampai Anda menghapusnya dengan Remove-Item Env:QUICKSTART_STEP:

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

Membuat contoh

Jika Anda lebih suka membangun dan menjalankannya langkah demi langkah, tulis contoh ke folder baru yang dinamai sesuai contoh itu:

Terminal window
aggrega scaffold --example quickstart-web

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd quickstart-web

Build

Perintah di bawah ini memulai langkah pertama, dari direktori contoh ini. Kata sandinya Anda pilih sendiri: Docker Compose membacanya dari shell Anda saat stack dimulai, sehingga tidak ada file yang menyimpannya.

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

Build menulis satu file, dist/compose/docker-compose.yaml, dan docker compose memulainya dengan nama proyek quickstart-web lalu kembali setelah kedua layanan aktif. Setiap bagian di bawah melangkah satu langkah lebih jauh.

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder workspace belum berisi folder `quickstart-web`, panggil alat `scaffold` sekali dengan `example` diatur ke `quickstart-web` dan tanpa `dir`: alat ini menulis contoh ke folder `quickstart-web` baru, dengan README dan folder langkah `1` hingga `4`. Lalu panggil alat `build` dengan `workspace_root` diatur ke `quickstart-web/1`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis build; file tersebut berada di bawah `quickstart-web/1/dist/`.

Aplikasi web dan PostgreSQL-nya — 1/

Aggregate mendeklarasikan dua komponen: web, bertipe core/compute/server, dan db, bertipe core/datastore/postgres. Aplikasi meminta database melalui sebuah edge, dengan nama-nama yang dibacanya:

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

Kata sandi mencapai kedua ujung melalui lampiran core/secret-value pada masing-masing, yang asalnya adalah referensi variabel Compose ${QUICKSTART_DB_PASSWORD}. Release menyebutkan image, yang disematkan dengan digest dari indeks multi-platformnya, port yang didengarkannya, port: 8080, dan published_port: 8080, port yang dipublikasikan untuknya di mesin Anda; tanpa published_port, tidak ada yang dipublikasikan di sana. Layanan web di 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 adalah db, nama layanan database di jaringan Compose, dan port hanya dipublikasikan di alamat loopback mesin Anda.

Buka http://127.0.0.1:8080/ di browser pada mesin yang sama untuk melihat halaman aplikasi. Halaman itu menyebutkan database dan cache yang terhubung dengan aplikasi, serta memungkinkan Anda menambahkan catatan dan membacanya. Setiap pembacaan menyebutkan asalnya, “from PostgreSQL” atau “from the cache”. Selama belum ada cache yang terhubung, halaman menampilkan “No cache is wired to the app, so every read comes from PostgreSQL.”

Dari terminal, tanyakan kepada aplikasi ke mana ia terhubung, lalu simpan sebuah catatan dan baca kembali:

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

Menambahkan cache — 2/

Aggregate menambahkan komponen cache bertipe core/datastore/redis, dan satu edge lagi pada aplikasi:

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

Manifest memetakan tipe baru ke compose/redis, dan Release menempatkan komponen baru. Build dan jalankan dengan nama proyek yang sama, dengan kata sandi yang sama masih diekspor:

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 membiarkan database tetap berjalan, membuat ulang aplikasi dengan dua variabel barunya, dan memulai cache. Database dibuat dengan kata sandi yang Anda ekspor di 1/ dan mempertahankannya, jadi gunakan nilai yang sama untuk langkah ini. Catatan yang disimpan di 1/ masih ada; baca dua kali:

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

Pembacaan pertama berasal dari PostgreSQL dan mengisi cache; yang kedua berasal dari cache, yang menyimpan catatan selama lima menit. Di halaman, membaca sebuah catatan dua kali menampilkan “from PostgreSQL”, lalu “from the cache”.

Setelah selesai dengan stack, hapus stack tersebut beserta data basis datanya:

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

Database yang sama, dikelola di AWS — 3/

Tiga komponen yang sama, di AWS, melalui Terraform. Manifest memetakan server ke terraform/server-ecs, layanan Amazon ECS di Fargate; PostgreSQL ke terraform/postgres-rds-terraform-aws-modules, yang menyertakan salinan modul RDS terbitan proyek terraform-aws-modules; dan Redis ke terraform/redis-elasticache, yang menyertakan salinan modul ElastiCache dari proyek itu. Edge di Aggregate tidak berubah.

Yang dihapus dari Aggregate adalah dua lampiran kata sandi: RDS membuat kata sandi database sendiri, sehingga tidak ada masukan build yang membawa kata sandi. Di AWS, RDS menyimpan kata sandi di AWS Secrets Manager, dan aplikasi quickstart, yang membaca kata sandinya hanya dari PGPASSWORD, tidak dapat masuk sampai Anda menyediakannya.

Release menyebutkan, di bawah infra.overrides, apa yang sudah Anda jalankan di akun Anda: klaster ECS, subnet dan grup keamanan tempat task terhubung, peran eksekusi yang digunakan ECS untuk menarik image dan menulis log, serta grup subnet RDS dan ElastiCache. Release juga menyetel engine_version cache ke 7.1, karena ElastiCache menjalankan Redis OSS hingga 7.1. Setiap nilai tersebut adalah placeholder: 123456789012 adalah nomor akun yang digunakan dokumentasi AWS dalam contoh, dan ID subnet-… dan sg-…, grup subnet, klaster, serta peran mewakili sumber daya di akun Anda sendiri. Build menerimanya karena build tidak pernah mencarinya; ganti nilai-nilai tersebut sebelum Anda membuat rencana.

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

Konfigurasi root, 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"]
}

Aplikasi menerima nama yang sama seperti di Compose. PGHOST dan REDIS_HOST kini merupakan referensi ke output milik modul RDS dan ElastiCache sendiri, yang di-resolve oleh Terraform saat menerapkan konfigurasi, karena kedua alamat itu belum ada sebelum instans dan cache dibuat; kompilator meneruskan keduanya tanpa membacanya. Pada salinan dist/terraform, tofu init -backend=false memuat root dan modul yang disertakan serta hanya mengambil penyedia, lalu tofu validate mencetak:

Success! The configuration is valid.

Menambahkan pencadangan — 4/

RDS menyimpan pencadangan otomatis instans selama 7 hari, dalam jendela waktu yang dipilihnya sendiri, jika tidak ada yang menyatakan lain — backup_retention_period = 7 di atas. Release melampirkan core/backup ke database:

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

dan Manifest mengikat Feature ke terraform/backup-native, yang tidak me-render apa pun sendiri: pencadangan adalah pengaturan instans, sehingga Recipe database membaca lampiran tersebut dan menuliskannya pada blok modul instans. RDS mengambil satu pencadangan otomatis per hari, sehingga jadwal membuka jendela 30 menit pada waktu tersebut, dalam UTC. Aggregate tidak berubah.

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

Konfigurasi root berbeda dari konfigurasi di 3/ hanya pada blok modul db, dan tofu validate padanya juga mencetak Success! The configuration is valid.:

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

Membangun bukan berarti men-deploy

3/ dan 4/ menulis file di bawah dist/ lalu berhenti. Build tidak pernah menjalankan Terraform atau OpenTofu, tidak pernah melakukan autentikasi ke AWS, dan tidak mencari satu pun pengidentifikasi yang disebutkan oleh Releases. Perencanaan dan penerapan adalah langkah yang Anda lakukan pada output, dengan kredensial Anda sendiri, setelah mengganti placeholder.

Memeriksa setiap langkah

Di checkout repositori dokumentasi, yang memuat skrip pembantu build bersama yang tidak disertakan oleh salinan yang ditulis aggrega scaffold --example, ./check.sh di direktori ini mem-build keempat langkah dan memeriksa bahwa masing-masing menulis apa yang ditunjukkan halaman ini: dua file Compose dengan layanan dan variabelnya, serta dua konfigurasi root Terraform dengan blok modul, referensi, dan pengaturan pencadangannya. Skrip ini mencetak satu baris per langkah dan keluar dengan kode bukan nol jika ada langkah yang berbeda. dist/, .aggrega/, dan file *.lock dihasilkan dan tidak di-commit; semuanya dibuat ulang dari file yang di-commit.