Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Eine Web-App mit PostgreSQL, Schritt für Schritt aufgebaut

Eine kleine Webanwendung, die Notizen in PostgreSQL speichert, in vier Schritten ausgebaut: Sie beginnt mit ihrer Datenbank auf Ihrem Rechner, erhält einen Redis-Cache, zieht mit der Datenbank auf Amazon RDS zu AWS um und bekommt schließlich ihre Backups. Jeder Schritt ist ein vollständiger eigener Workspace, in den Verzeichnissen 1/ bis 4/, und jeder lässt sich so, wie er ist, bauen.

Jedes aggregate.yaml beginnt mit einem einzeiligen Kommentar, der seinen Schritt nennt, und ebenso ein release.yaml oder ein manifest.yaml, wo dieser Schritt es ändert. Der Vergleich einer Datei mit der des vorherigen Schritts zeigt genau, was der Schritt hinzufügt:

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

Die Anwendung ist hub.aggrega.ai/tools/quickstart-web:1.1.0, unter der Lizenz Apache-2.0. Sie liest ihre Konfiguration ausschließlich aus ihrer Umgebung: PGHOST, PGPORT, PGUSER, PGPASSWORD und PGDATABASE für PostgreSQL sowie REDIS_HOST und REDIS_PORT für einen Cache, den sie nur verwendet, solange REDIS_HOST gesetzt ist. Sie lauscht auf Port 8080, und jede Antwort zu einer Notiz gibt in ihrem Feld source an, woher die Notiz gelesen wurde, sodass der Cache von außen sichtbar ist.

Die Ausgabeblöcke auf dieser Seite sind aus einem echten Lauf kopiert, gemäß Die Ausgabe auf diesen Seiten lesen.

Was Sie brauchen

  • Die CLI aggrega, für jeden Schritt.
  • Docker mit Compose, für 1/ und 2/, die auf Ihrem Rechner laufen.
  • Nichts weiter für 3/ und 4/: Sie bauen Terraform-Dateien und halten an. Der erste Build jedes dieser Schritte lädt die RDS- und ElastiCache-Module aus ihren Git-Repositorys. Diese Dateien zu planen und anzuwenden ist ein eigener Vorgang, den Sie mit Ihrem eigenen AWS-Konto und Ihren Zugangsdaten durchführen, sobald die Platzhalter ersetzt sind.

Mit einem einzigen Befehl ausführen

Sie können den ersten Schritt mit einem einzigen Befehl ausführen oder ihn von Ihrem KI-Assistenten schreiben und bauen lassen.

Wählen Sie ein Passwort für die Datenbank und exportieren Sie es zuerst. Unter Linux oder macOS:

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

Unter Windows in PowerShell:

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

Das Passwort muss exportiert werden, weil Docker Compose es aus Ihrer Shell liest, und die Datenbank behält das erste Passwort, mit dem sie gestartet wurde, sodass der zweite Schritt dasselbe benötigt. Ohne das Passwort verweigert das Skript den Start.

Das Skript sagt, was es tun wird, und fragt, bevor es fortfährt. Es prüft, ob es aggrega finden kann und ob Docker antwortet und Compose hat. Es schreibt das Beispiel in den Ordner quickstart-web oder verwendet diesen Ordner, wenn er bereits vorhanden ist. Anschließend baut es den ersten Schritt und startet ihn mit Docker Compose. Zum Schluss gibt das Skript die Seite der App aus, http://127.0.0.1:8080/.

Um einen anderen Schritt auszuführen, nennen Sie ihn: 2, 3 oder 4; die Schritte 3 und 4 bauen nur. Unter Linux oder macOS übergeben Sie ihn nach sh -s -- und fügen dort --yes hinzu, um ohne die Rückfrage fortzufahren:

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

Setzen Sie ihn in PowerShell zuerst in QUICKSTART_STEP. Er bleibt in diesem Fenster für jeden späteren Lauf gesetzt, bis Sie ihn mit Remove-Item Env:QUICKSTART_STEP entfernen:

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

Das Beispiel generieren

Wenn Sie es lieber Schritt für Schritt bauen und ausführen möchten, schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

Terminal window
aggrega scaffold --example quickstart-web

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd quickstart-web

Build

Die folgenden Befehle starten den ersten Schritt aus dem Verzeichnis dieses Beispiels. Das Passwort wählen Sie selbst: Docker Compose liest es beim Start des Stacks aus Ihrer Shell, sodass keine Datei es enthält.

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

Der Build schreibt eine einzige Datei, dist/compose/docker-compose.yaml, und docker compose startet sie unter dem Projektnamen quickstart-web und kehrt zurück, sobald beide Services laufen. Jeder folgende Abschnitt geht einen Schritt weiter.

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie nur die Aggrega-Werkzeuge, und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `quickstart-web` enthält, rufen Sie das Werkzeug `scaffold` einmal mit `example` auf `quickstart-web` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `quickstart-web`, mit einer README und den Schrittordnern `1` bis `4`. Rufen Sie dann das Werkzeug `build` mit `workspace_root` auf `quickstart-web/1`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt auf. Sagen Sie mir, welche Dateien der Build geschrieben hat; sie liegen unter `quickstart-web/1/dist/`.

Eine Web-App und ihr PostgreSQL — 1/

Das Aggregate deklariert zwei Komponenten: web vom Typ core/compute/server und db vom Typ core/datastore/postgres. Die Anwendung fordert die Datenbank über eine Kante an, unter den Namen, die sie liest:

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

Das Passwort erreicht beide Enden über eine Anbindung core/secret-value an jedem, deren Herkunft die Compose-Variablenreferenz ${QUICKSTART_DB_PASSWORD} ist. Das Release benennt das Image, per Digest seines Multi-Plattform-Index fixiert, den Port, auf dem es lauscht, port: 8080, und published_port: 8080, den Port, der dafür auf Ihrem Rechner veröffentlicht wird; ohne published_port wird dort nichts veröffentlicht. Der Service web in 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 ist db, der Servicename der Datenbank im Compose-Netzwerk, und der Port wird nur auf der Loopback-Adresse Ihres Rechners veröffentlicht.

Öffnen Sie http://127.0.0.1:8080/ in einem Browser auf demselben Rechner, um die Seite der App zu sehen. Sie nennt die Datenbank und den Cache, mit denen die App verbunden ist, und lässt Sie eine Notiz hinzufügen und lesen. Jeder Lesevorgang gibt an, woher er kam, „from PostgreSQL“ oder „from the cache“. Solange noch kein Cache verbunden ist, zeigt die Seite „No cache is wired to the app, so every read comes from PostgreSQL.“

Fragen Sie in einem Terminal die Anwendung, womit sie verbunden ist, speichern Sie dann eine Notiz und lesen Sie sie zurück:

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

Einen Cache hinzufügen — 2/

Das Aggregate fügt eine Komponente cache vom Typ core/datastore/redis hinzu und eine weitere Kante an der Anwendung:

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

Das Manifest bildet den neuen Typ auf compose/redis ab, und das Release platziert die neue Komponente. Bauen und starten Sie sie unter demselben Projektnamen, mit demselben weiterhin exportierten Passwort:

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 lässt die Datenbank weiterlaufen, erstellt die Anwendung mit ihren zwei neuen Variablen neu und startet den Cache. Die Datenbank wurde mit dem Passwort erstellt, das Sie bei 1/ exportiert haben, und behält es, also behalten Sie für diesen Schritt denselben Wert bei. Die bei 1/ gespeicherte Notiz ist noch da; lesen Sie sie zweimal:

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

Der erste Lesevorgang kommt aus PostgreSQL und füllt den Cache; der zweite kommt aus dem Cache, der eine Notiz fünf Minuten lang hält. Auf der Seite zeigt das zweimalige Lesen einer Notiz „from PostgreSQL“, dann „from the cache“.

Wenn Sie mit dem Stack fertig sind, entfernen Sie ihn, mitsamt den Daten der Datenbank:

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

Dieselbe Datenbank, verwaltet auf AWS — 3/

Dieselben drei Komponenten, auf AWS, über Terraform. Das Manifest bildet den Server auf terraform/server-ecs ab, einen Amazon-ECS-Service auf Fargate; PostgreSQL auf terraform/postgres-rds-terraform-aws-modules, das eine Kopie des veröffentlichten RDS-Moduls des Projekts terraform-aws-modules mitliefert; und Redis auf terraform/redis-elasticache, das eine Kopie von dessen ElastiCache-Modul mitliefert. Die Kanten im Aggregate ändern sich nicht.

Was das Aggregate weglässt, sind die beiden Passwort-Anbindungen: RDS erzeugt das Passwort der Datenbank selbst, daher trägt keine Build-Eingabe eines. Auf AWS bewahrt RDS das Passwort in AWS Secrets Manager auf, und die Quickstart-Anwendung, die ihr Passwort nur aus PGPASSWORD liest, kann sich erst anmelden, wenn Sie es bereitstellen.

Das Release benennt unter infra.overrides, was Sie in Ihrem Konto bereits betreiben: den ECS-Cluster, die Subnetze und Sicherheitsgruppen, mit denen die Tasks verbunden werden, die Ausführungsrolle, mit der ECS das Image abruft und Logs schreibt, sowie die Subnetzgruppen von RDS und ElastiCache. Außerdem setzt es die engine_version des Caches auf 7.1, weil ElastiCache Redis OSS bis 7.1 ausführt. Jeder dieser Werte ist ein Platzhalter: 123456789012 ist die Kontonummer, die die AWS-Dokumentation in Beispielen verwendet, und die IDs subnet-… und sg-…, die Subnetzgruppen, der Cluster und die Rolle stehen für Ressourcen in Ihrem eigenen Konto. Der Build akzeptiert sie, weil er sie nie nachschlägt; ersetzen Sie sie, bevor Sie planen.

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

Die Root-Konfiguration, 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"]
}

Die Anwendung erhält dieselben Namen wie auf Compose. PGHOST und REDIS_HOST sind jetzt Referenzen auf die eigenen Ausgaben der RDS- und ElastiCache-Module, die Terraform auflöst, wenn es die Konfiguration anwendet, weil keine der beiden Adressen existiert, bevor die Instanz und der Cache erstellt sind; der Compiler reicht beide durch, ohne sie zu lesen. Auf einer Kopie von dist/terraform lädt tofu init -backend=false die Root-Konfiguration und die mitgelieferten Module und ruft nur Provider ab, und tofu validate gibt dann aus:

Success! The configuration is valid.

Backups hinzufügen — 4/

RDS bewahrt die automatisierten Backups der Instanz 7 Tage lang auf, in einem Zeitfenster, das es selbst wählt, wenn nichts anderes angegeben ist — backup_retention_period = 7 oben. Das Release bindet core/backup an die Datenbank an:

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

und das Manifest bindet das Feature an terraform/backup-native, das nichts Eigenes rendert: Das Backup ist eine Einstellung der Instanz, daher liest das Datenbank-Recipe die Anbindung und schreibt sie in den Modulblock der Instanz. RDS erstellt ein automatisiertes Backup pro Tag, daher öffnet der Zeitplan zu dieser Uhrzeit ein 30-minütiges Fenster, in UTC. Das Aggregate ändert sich nicht.

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

Die Root-Konfiguration unterscheidet sich von der bei 3/ nur im Modulblock db, und tofu validate gibt auch dafür Success! The configuration is valid. aus:

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

Bauen ist nicht Bereitstellen

3/ und 4/ schreiben Dateien unter dist/ und halten an. Der Build führt nie Terraform oder OpenTofu aus, authentifiziert sich nie bei AWS und schlägt keinen der Bezeichner nach, die die Releases benennen. Planen und Anwenden sind Schritte, die Sie mit Ihren eigenen Zugangsdaten an der Ausgabe vornehmen, nachdem Sie die Platzhalter ersetzt haben.

Jeden Schritt prüfen

In einem Checkout des Dokumentations-Repositorys, das den gemeinsamen Build-Helfer enthält, den eine von aggrega scaffold --example geschriebene Kopie nicht mitbringt, baut ./check.sh in diesem Verzeichnis die vier Schritte und prüft, dass jeder schreibt, was diese Seite zeigt: die beiden Compose-Dateien mit ihren Services und Variablen sowie die beiden Terraform-Root-Konfigurationen mit ihren Modulblöcken, ihren Referenzen und ihren Backup-Einstellungen. Es gibt eine Zeile pro Schritt aus und endet mit einem Exit-Code ungleich null, wenn ein Schritt abweicht. dist/, .aggrega/ und die Dateien *.lock werden erzeugt und nicht committet; sie werden aus den Dateien neu erzeugt, die es sind.