Blueprints

A blueprint is a template for a complete application stack: its containers, the managed database it needs, and the secrets that tie them together. Deploying one creates all of it in a resource group you choose, under an instance name you choose, in one operation.

What a deploy creates

• A container instance with the instance name — the blueprint's containers with their start order, health checks, endpoints and compute. It is an ordinary container instance and is managed like any other; its overview shows the Template it was deployed from.
• The managed resources the blueprint declares — today PostgreSQL databases — named <instance>-<resource>. They are platform resources in their own right, and they are not deleted with the instance.
• A vault named <instance>-secrets, when the blueprint has anything secret: the secret parameters you entered or had generated, and the connection details of its managed resources. The instance's identity is given Secrets Reader on the vault, and the containers receive the values when they start.

A blueprint with no secrets and no managed resources creates only the container instance. What you do with the result afterwards is described in After a deploy.

Where blueprints come from

Origin	What it is	Listed in
Platform catalog	The blueprints shipped with the platform release — PocketBase, Supabase and Stackship Data Hub among them — plus those pulled from the catalog repository chosen at installation. By default that is Stackship's public catalog, which adds more, Keycloak among them	Every boundary
Catalog sources	Git repositories a boundary connects to publish its own blueprints — see Catalog sources	That boundary
Boundary templates	Templates saved to a boundary through the API — see Publish templates with the API	That boundary

Each blueprint has a slug, its identifier. The platform catalog owns its slugs: a boundary cannot publish a blueprint under a slug the platform catalog uses. When the platform catalog later takes a slug a boundary already uses, deploying that slug deploys the platform's blueprint. Blueprints tagged stackship are built and maintained by Stackship, and the catalog lists them first.

How a deploy runs

Before anything is created, the platform checks every permission and name the deploy will need, in the order it will need them, and refuses the deploy — creating nothing — when one of them fails. See Preflight checks.

A deploy that passes is accepted at once and runs as an operation you can follow. Its steps run in this order:

Step	What it does	When
Prepare the instance vault	Creates <instance>-secrets	The blueprint needs a vault
Write parameters and generated secrets	Writes every secret parameter into the vault	The blueprint needs a vault
Provision postgres '<name>'	Creates the database, waits up to five minutes for it to accept connections, and writes its connection details into the vault	Once per managed resource
Create the container instance	Creates the instance with the compute you chose. First, the instance's identity is given Secrets Reader on every vault its containers read from	Always
Grant the instance access to its vault	Gives the instance's identity Secrets Reader on the vault	The blueprint needs a vault

Everything is created with your own permissions, not the platform's.

A blueprint's containers read secrets only from the instance vault: a template whose secretRef names any other vault is rejected when it is published, and refused at deploy if it was stored before that rule. A first deploy is also refused when a vault with the instance vault's name already exists, since the new instance would get read access to everything in it.

Caution

A blueprint runs images its author chose, with read access to the instance vault granted with your permissions. Anyone who can publish templates to the boundary — with blueprints/templates/write, or by pushing to the repository of a catalog source — decides what those images are. Review a blueprint from a catalog source or the templates API before you deploy it.

When a deploy fails

What the steps before the failure created stays in the resource group, and the error message names it. That is deliberate: a deploy usually fails on something you are about to fix, and retrying it reuses the vault and the database instead of creating them again — see Retry a failed deploy. If you are not going to retry, delete what was left.

If the Blueprints service restarts while a deploy is queued or running, the deploy fails with a message asking you to retry it.

Pages

• Deploy a blueprint
• Catalog sources — publish your team's blueprints from a git repository
• After a deploy
• Write your own blueprints
• Custom Keycloak theme
• Permissions