Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Une application web avec PostgreSQL, construite étape par étape

Une petite application web qui conserve des notes dans PostgreSQL, développée en quatre étapes : elle commence avec sa base de données sur votre machine, gagne un cache Redis, passe sur AWS avec la base de données sur Amazon RDS, et reçoit enfin ses sauvegardes. Chaque étape est un espace de travail complet à part entière, dans les répertoires 1/ à 4/, et chacune se construit telle quelle.

Chaque aggregate.yaml s’ouvre sur un commentaire d’une ligne qui nomme son étape, tout comme un release.yaml ou un manifest.yaml là où cette étape le modifie. Comparer un fichier avec celui de l’étape précédente montre exactement ce que l’étape ajoute :

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

L’application est hub.aggrega.ai/tools/quickstart-web:1.1.0, sous licence Apache-2.0. Elle lit sa configuration uniquement depuis son environnement : PGHOST, PGPORT, PGUSER, PGPASSWORD et PGDATABASE pour PostgreSQL, et REDIS_HOST et REDIS_PORT pour un cache, qu’elle n’utilise que tant que REDIS_HOST est définie. Elle écoute sur le port 8080, et chaque réponse concernant une note indique d’où la note a été lue, dans son champ source, si bien que le cache est visible de l’extérieur.

Les blocs de sortie de cette page sont copiés d’une exécution réelle, conformément à Lire la sortie sur ces pages.

Ce dont vous avez besoin

  • La CLI aggrega, pour chaque étape.
  • Docker avec Compose, pour 1/ et 2/, qui s’exécutent sur votre machine.
  • Rien de plus pour 3/ et 4/ : ils construisent des fichiers Terraform et s’arrêtent. Le premier build de chacun récupère les modules RDS et ElastiCache depuis leurs dépôts git. Planifier et appliquer ces fichiers est un acte distinct, effectué avec votre propre compte AWS et vos propres informations d’identification une fois les espaces réservés remplacés.

Le lancer en une seule commande

Vous pouvez exécuter la première étape avec une seule commande, ou demander à votre assistant IA de l’écrire et de la construire pour vous.

Choisissez un mot de passe pour la base de données et exportez-le d’abord. Sous Linux ou macOS :

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

Sous Windows, dans PowerShell :

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

Le mot de passe doit être exporté, car Docker Compose le lit depuis votre shell, et la base de données conserve le premier mot de passe avec lequel elle a été démarrée, si bien que la deuxième étape a besoin du même. Le script refuse de démarrer sans lui.

Le script indique ce qu’il va faire et demande confirmation avant de continuer. Il vérifie qu’il trouve aggrega, et que Docker répond et dispose de Compose. Il écrit l’exemple dans le dossier quickstart-web, ou utilise ce dossier s’il existe déjà. Il construit ensuite la première étape et la démarre avec Docker Compose. Le script se termine en affichant la page de l’application, http://127.0.0.1:8080/.

Pour exécuter une autre étape, indiquez-la : 2, 3 ou 4 ; les étapes 3 et 4 se contentent de construire. Sous Linux ou macOS, passez-la après sh -s --, et ajoutez-y --yes pour continuer sans la question :

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

Dans PowerShell, définissez-la d’abord dans QUICKSTART_STEP. Elle reste définie dans cette fenêtre, pour chaque exécution ultérieure, jusqu’à ce que vous la supprimiez avec Remove-Item Env:QUICKSTART_STEP :

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

Générer l’exemple

Si vous préférez le construire et l’exécuter pas à pas, écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example quickstart-web

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd quickstart-web

Build

Les commandes ci-dessous démarrent la première étape, depuis le répertoire de cet exemple. Le mot de passe est à votre choix : Docker Compose le lit depuis votre shell au démarrage de la stack, si bien qu’aucun fichier ne le contient.

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

Le build écrit un seul fichier, dist/compose/docker-compose.yaml, et docker compose le démarre sous le nom de projet quickstart-web et rend la main dès que les deux services sont en marche. Chaque section ci-dessous fait avancer d’une étape.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils d’Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `quickstart-web`, appelez une fois l’outil `scaffold` avec `example` défini sur `quickstart-web` et sans `dir` : il écrit l’exemple dans un nouveau dossier `quickstart-web`, avec un README et les dossiers d’étapes `1` à `4`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `quickstart-web/1`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `quickstart-web/1/dist/`.

Une application web et son PostgreSQL — 1/

L’Aggregate déclare deux composants : web, de type core/compute/server, et db, de type core/datastore/postgres. L’application demande la base de données sur une arête, sous les noms qu’elle lit :

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

Le mot de passe atteint les deux extrémités via un rattachement core/secret-value sur chacune, dont l’origine est la référence de variable Compose ${QUICKSTART_DB_PASSWORD}. La Release nomme l’image, épinglée par le digest de son index multiplateforme, le port sur lequel elle écoute, port: 8080, et published_port: 8080, le port publié pour elle sur votre machine ; sans published_port, rien n’y est publié. Le service web dans 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 est db, le nom de service de la base de données sur le réseau Compose, et le port n’est publié que sur l’adresse de bouclage de votre machine.

Ouvrez http://127.0.0.1:8080/ dans un navigateur sur la même machine pour voir la page de l’application. Elle indique la base de données et le cache auxquels l’application est connectée, et vous permet d’ajouter une note et de la lire. Chaque lecture indique sa provenance, « from PostgreSQL » ou « from the cache ». Tant qu’aucun cache n’est encore raccordé, la page affiche « No cache is wired to the app, so every read comes from PostgreSQL. »

Depuis un terminal, demandez à l’application à quoi elle est connectée, puis enregistrez une note et relisez-la :

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

Ajouter un cache — 2/

L’Aggregate ajoute un composant cache de type core/datastore/redis, et une arête de plus sur l’application :

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

Le Manifest associe le nouveau type à compose/redis, et la Release place le nouveau composant. Construisez-le et démarrez-le sous le même nom de projet, avec le même mot de passe toujours exporté :

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 laisse la base de données en marche, recrée l’application avec ses deux nouvelles variables et démarre le cache. La base de données a été créée avec le mot de passe que vous avez exporté à 1/ et le conserve, donc gardez la même valeur pour cette étape. La note enregistrée à 1/ est toujours là ; lisez-la deux fois :

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

La première lecture provient de PostgreSQL et remplit le cache ; la seconde provient du cache, qui conserve une note pendant cinq minutes. Sur la page, lire une note deux fois affiche « from PostgreSQL », puis « from the cache ».

Lorsque vous avez terminé avec la pile, supprimez-la, avec les données de la base de données :

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

Même base de données, managée sur AWS — 3/

Les trois mêmes composants, sur AWS, via Terraform. Le Manifest associe le serveur à terraform/server-ecs, un service Amazon ECS sur Fargate ; PostgreSQL à terraform/postgres-rds-terraform-aws-modules, qui embarque une copie du module RDS publié par le projet terraform-aws-modules ; et Redis à terraform/redis-elasticache, qui embarque une copie de son module ElastiCache. Les arêtes de l’Aggregate ne changent pas.

Ce que l’Aggregate abandonne, ce sont les deux rattachements de mot de passe : RDS génère lui-même le mot de passe de la base de données, si bien qu’aucune entrée du build n’en porte. Sur AWS, RDS conserve le mot de passe dans AWS Secrets Manager, et l’application quickstart, qui ne lit son mot de passe que depuis PGPASSWORD, ne peut pas se connecter tant que vous ne le fournissez pas.

La Release nomme, sous infra.overrides, ce que vous exécutez déjà dans votre compte : le cluster ECS, les sous-réseaux et groupes de sécurité auxquels les tâches sont reliées, le rôle d’exécution avec lequel ECS récupère l’image et écrit les logs, et les groupes de sous-réseaux RDS et ElastiCache. Elle définit aussi l’engine_version du cache à 7.1, parce qu’ElastiCache exécute Redis OSS jusqu’à la version 7.1. Chacune de ces valeurs est un espace réservé : 123456789012 est le numéro de compte que la documentation AWS utilise dans ses exemples, et les ID subnet-… et sg-…, les groupes de sous-réseaux, le cluster et le rôle représentent des ressources de votre propre compte. Le build les accepte parce qu’il ne les recherche jamais ; remplacez-les avant de planifier.

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

La configuration racine, 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"]
}

L’application reçoit les mêmes noms que sur Compose. PGHOST et REDIS_HOST sont désormais des références aux sorties propres des modules RDS et ElastiCache, que Terraform résout lorsqu’il applique la configuration, parce qu’aucune des deux adresses n’existe avant la création de l’instance et du cache ; le compilateur les fait passer toutes deux sans les lire. Sur une copie de dist/terraform, tofu init -backend=false charge la racine et les modules embarqués et ne récupère que les fournisseurs, puis tofu validate affiche :

Success! The configuration is valid.

Ajouter les sauvegardes — 4/

RDS conserve les sauvegardes automatisées de l’instance pendant 7 jours, dans une fenêtre qu’il choisit, lorsque rien n’indique le contraire — backup_retention_period = 7 ci-dessus. La Release rattache core/backup à la base de données :

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

et le Manifest lie la Feature à terraform/backup-native, qui ne rend rien qui lui soit propre : la sauvegarde est un paramètre de l’instance, si bien que la Recipe de la base de données lit le rattachement et l’écrit sur le bloc de module de l’instance. RDS effectue une sauvegarde automatisée par jour, si bien que la planification ouvre une fenêtre de 30 minutes à cette heure-là, en UTC. L’Aggregate ne change pas.

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

La configuration racine ne diffère de celle de 3/ que par le bloc de module db, et tofu validate sur celle-ci affiche aussi Success! The configuration is valid. :

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

Construire n’est pas déployer

3/ et 4/ écrivent des fichiers sous dist/ et s’arrêtent. Le build n’exécute jamais Terraform ni OpenTofu, ne s’authentifie jamais auprès d’AWS et ne recherche aucun des identifiants que nomment les Releases. Planifier et appliquer sont des étapes que vous effectuez sur la sortie, avec vos propres informations d’identification, après avoir remplacé les espaces réservés.

Vérifier chaque étape

Dans un checkout du dépôt de la documentation, qui contient l’assistant de build partagé qu’une copie écrite par aggrega scaffold --example n’emporte pas, ./check.sh dans ce répertoire construit les quatre étapes et vérifie que chacune écrit ce que montre cette page : les deux fichiers Compose avec leurs services et leurs variables, et les deux configurations racines Terraform avec leurs blocs de module, leurs références et leurs paramètres de sauvegarde. Il affiche une ligne par étape et se termine avec un code non nul si une étape diffère. dist/, .aggrega/ et les fichiers *.lock sont générés et ne sont pas commités ; ils se régénèrent à partir des fichiers qui le sont.