Catalog-only — MariaDB + Adminer with zero platform authoring
This example deploys a small, real stack — a MariaDB database with an Adminer web UI in front of it — by referencing standard-library catalog entities only. No Component, Feature, or Recipe is authored here: three short YAML files route everything to entities the catalog already ships.
It is the smallest authoring surface Aggrega offers, and the natural first contact with the language. The Authoring-tier sibling deploys the same stack while building its own catalog layer — read this example first to see what a finished catalog buys you, then that one to learn how the layer underneath is made.
The three files
aggregate.yaml— the Developer’s intent: what the stack is. Two components picked from the catalog bytype:, a required credential as a slot-filling attachment, and oneusesedge wiring the database into Adminer’sdatabasessocket.release.yaml— the Operator’s per-environment fulfillment: how big and where. Theinfra:blocks (engine version, storage size, published port) belong to the Operator; the Aggregate never carries them.manifest.yaml— the Operator’s routing: which Recipe realises each type on this target. See below for why the references are provider-qualified.
What it demonstrates
- Components as catalog references.
type: core/datastore/mariadbandtype: core/devtool/adminerare the entire compute declaration. The Developer authors only the values the Component schemas expose — every omitted field takes its schema default (compare the rendered output’s charset and collation env vars with the one-linevalues:block that produced them). - The String Pipe. Adminer’s catalog Component declares a
databasesuses-socket accepting any component labeledcomponent.aggrega.ai/type=stateful-server. The Aggregate’s edge injects the database Recipe’sprovides.hostintoADMINER_DEFAULT_SERVER. The compiler routes the string without interpreting it — on this target it is a compose service name; the same edge on a Kubernetes target would carry a Service DNS name. - The attachment pillar. The database Component’s
featuresSchemarequires aroot_passwordslot, filled with the catalog’score/secret-valueFeature. The slot is black-box: the FeatureRecipe selected by the Manifest controls delivery, and the Developer cannot dictate it. - Provider-qualified Recipe routing. The Manifest maps
core/datastore/mariadb:1.0.0tocompose/mariadb:1.0.0— qualified by provider — because the standard library ships a mariadb Recipe under more than one provider (compose and helm among them). The Operator’s mapping is what disambiguates the target: a bare, unqualified reference that matches more than one provider’s Recipe halts the build loudly rather than silently picking one. Re-target the stack by re-pointing these mappings; the Aggregate does not change.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example catalog-onlyIt then prints the commands to run next. The first changes into the new folder:
cd catalog-onlyBuild
From this directory, with the catalog entities resolved from hub.aggrega.ai,
the default registry .aggrega-config.yaml names:
aggrega pull --release release.yamlaggrega build --release release.yamlThe pull resolves every referenced entity and pins it in release.lock
(identity + content digest; run it again to regenerate a stale lockfile).
With a checkout of the standard-library catalog
(where to get one), name its
aggrega-catalog directory with --catalog on both commands to read the entities from there.
The build reads that lockfile — without it, the build halts and names the two ways forward, the pull or --auto-pull
— and renders dist/compose/docker-compose.yaml. The Release authors its components
directly (no boundaries: block), so the compiler folds them into the
synthesized default scope and emits flat under dist/ — one boundary, no
boundary-name segment in the path.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `catalog-only` folder yet, call the `scaffold` tool once with `example` set to `catalog-only` and no `dir`: it writes the example into a new `catalog-only` folder. Then call the `build` tool with `workspace_root` set to `catalog-only`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `catalog-only/dist/`.Read the output
The rendered compose file is where the wiring becomes visible:
- the
webservice carriesADMINER_DEFAULT_SERVER: db— the database Recipe’sprovides.host(the compose service name) delivered through the uses edge; - the same edge produced
depends_on: [db]— topology, not just strings; - the
dbservice’sMARIADB_CHARACTER_SET_SERVERandMARIADB_COLLATION_SERVERcome from schema defaults the Aggregate never mentions; image: mariadb:11.4and the8080:8080port binding come from the Release’sinfra:blocks — the Operator’s pillar, rendered next to the Developer’s.
Run
cd dist/composedocker compose up -dOpen http://localhost:8080: the server field is pre-filled with db.
Log in as root with the development password from the Aggregate’s
attachment (dev-root-pw-change-me — a placeholder to replace in
anything beyond local development), database appdb.
Where next
The Authoring tier builds this same platform layer yourself — the Components, Recipes, and credential FeatureRecipes this example consumed ready-made — and compiles one Aggregate to four targets.