PostgreSQL을 사용하는 웹 앱을 한 단계씩 구축하기
메모를 PostgreSQL에 보관하는 작은 웹 애플리케이션을 네 단계에 걸쳐 키워 갑니다. 로컬 머신의 데이터베이스와 함께 시작하여, Redis 캐시를 추가하고, 데이터베이스를 Amazon RDS에 두고 AWS로 옮기며, 마지막으로 백업을 갖춥니다. 각 단계는 디렉터리 1/부터 4/까지에 있는 그 자체로 완전한 작업 공간이며, 각각 있는 그대로 빌드됩니다.
모든 aggregate.yaml은 해당 단계를 나타내는 한 줄 주석으로 시작하며, 해당 단계에서 release.yaml이나 manifest.yaml을 변경하는 경우 그 파일도 마찬가지입니다. 파일을 이전 단계의 파일과 비교하면 그 단계에서 무엇이 추가되는지 정확히 알 수 있습니다:
diff 1/aggregate.yaml 2/aggregate.yaml애플리케이션은 Apache-2.0 라이선스로 제공되는 hub.aggrega.ai/tools/quickstart-web:1.1.0입니다. 구성은 환경 변수에서만 읽습니다. PostgreSQL에는 PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE를, 캐시에는 REDIS_HOST와 REDIS_PORT를 사용하며, 캐시는 REDIS_HOST가 설정된 동안에만 사용합니다. 포트 8080에서 수신 대기하며, 메모에 관한 모든 응답은 source 필드에서 그 메모를 어디서 읽었는지 알려 주므로 캐시가 외부에서 보입니다.
이 페이지의 출력 블록은 이 페이지의 출력 읽기에 따라 실제 실행에서 복사한 것입니다.
준비물
- 모든 단계에 필요한
aggregaCLI. - 로컬 머신에서 실행되는
1/과2/에 필요한 Compose 포함 Docker. 3/과4/에는 더 필요한 것이 없습니다. 이 단계들은 Terraform 파일을 빌드하고 멈춥니다. 각각의 첫 빌드는 RDS 및 ElastiCache 모듈을 해당 git 저장소에서 가져옵니다. 이 파일들의 계획과 적용은 별도의 작업으로, 자리 표시자를 교체한 뒤 본인의 AWS 계정과 자격 증명으로 수행합니다.
명령 하나로 실행하기
첫 번째 단계는 명령 하나로 실행하거나, AI 어시스턴트가 작성하고 빌드하도록 맡길 수 있습니다.
데이터베이스 비밀번호를 정하고 먼저 내보냅니다. Linux 또는 macOS에서:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shWindows에서는 PowerShell에서 다음을 실행합니다:
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexDocker 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 -- 2PowerShell에서는 먼저 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으로 시작하며, 두 서비스가 모두 올라오면 반환합니다. 아래의 각 섹션은 한 단계씩 더 나아갑니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `quickstart-web` 폴더가 없으면 `example`을 `quickstart-web`으로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 README와 단계 폴더 `1`부터 `4`까지가 포함된 새 `quickstart-web` 폴더에 예제가 작성됩니다. 그런 다음 `workspace_root`를 `quickstart-web/1`로, `release`를 `release.yaml`로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `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는 Compose 네트워크에서 데이터베이스의 서비스 이름인 db이며, 포트는 로컬 머신의 루프백 주소에만 게시됩니다.
같은 머신의 브라우저에서 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는 새 컴포넌트를 배치합니다. 같은 비밀번호를 export한 상태 그대로, 같은 프로젝트 이름으로 빌드하고 시작합니다:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose는 데이터베이스를 계속 실행한 채, 두 개의 새 변수로 애플리케이션을 다시 만들고 캐시를 시작합니다. 데이터베이스는 1/에서 export한 비밀번호로 생성되었고 그 비밀번호를 유지하므로, 이 단계에서도 같은 값을 유지하십시오. 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에서 이루어지며 캐시를 채우고, 두 번째 읽기는 캐시에서 이루어집니다. 캐시는 메모를 5분 동안 보관합니다. 페이지에서 메모를 두 번 읽으면 “from PostgreSQL”, 이어서 “from the cache”가 표시됩니다.
스택 사용을 마치면 데이터베이스의 데이터까지 함께 제거합니다.
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -v같은 데이터베이스를 AWS 관리형으로 — 3/
같은 세 컴포넌트를 Terraform을 통해 AWS에서 실행합니다. Manifest는 서버를 Fargate 기반 Amazon ECS 서비스인 terraform/server-ecs에, PostgreSQL을 terraform-aws-modules 프로젝트가 게시한 RDS 모듈을 벤더링한 terraform/postgres-rds-terraform-aws-modules에, Redis를 같은 프로젝트의 ElastiCache 모듈을 벤더링한 terraform/redis-elasticache에 매핑합니다. Aggregate의 엣지는 바뀌지 않습니다.
Aggregate에서 빠지는 것은 두 개의 비밀번호 어태치먼트입니다. RDS가 데이터베이스의 비밀번호를 직접 생성하므로 어떤 빌드 입력도 비밀번호를 담고 있지 않습니다. AWS에서 RDS는 비밀번호를 AWS Secrets Manager에 보관하며, 비밀번호를 PGPASSWORD에서만 읽는 quickstart 애플리케이션은 비밀번호를 제공하기 전까지 로그인할 수 없습니다.
Release는 infra.overrides 아래에 계정에서 이미 실행 중인 리소스를 지정합니다. ECS 클러스터, 태스크가 연결되는 서브넷과 보안 그룹, ECS가 이미지를 가져오고 로그를 기록할 때 사용하는 실행 역할, 그리고 RDS 및 ElastiCache 서브넷 그룹입니다. 또한 캐시의 engine_version을 7.1로 설정합니다. ElastiCache가 Redis OSS를 7.1까지만 실행하기 때문입니다. 이 값들은 모두 자리 표시자입니다: 123456789012는 AWS 문서가 예제에서 사용하는 계정 번호이며, subnet-… 및 sg-… ID, 서브넷 그룹, 클러스터, 역할은 본인 계정의 리소스를 나타냅니다. 빌드는 이 값들을 조회하지 않으므로 그대로 받아들입니다. 계획하기 전에 교체하십시오.
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는 하루에 한 번 자동 백업을 수행하므로, 일정은 그 시각에 UTC 기준으로 30분 길이의 시간대를 엽니다. 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 루트 구성입니다. 단계마다 한 줄을 출력하며, 어느 단계라도 다르면 0이 아닌 코드로 종료합니다. dist/, .aggrega/, *.lock 파일은 생성된 것이며 커밋되지 않습니다. 이들은 커밋된 파일로부터 다시 생성됩니다.