The Deployer documentation
Creating & deploying a project

Blueprints: reuse a whole setup

A blueprint is a file that describes how an app is deployed: every choice you made, and none of your secrets. Use it to set up the same deployment again with another repository, another cloud account or another domain, without choosing everything again.

What a blueprint holds

  • The repository, its branch and the service to deploy.
  • The hosting plan: what kind of hosting, its size, the database and cache (and whether the database has a standby copy).
  • The workflow choices and extras: uptime checks, crash reports, alert rules, charts, searchable logs, backups.
  • The web address, and who can open the app (networks, saved group names, or a password's user name).
  • The names of your settings, which of them are wired for you (DATABASE_URL) and which are random secrets generated for you (SECRET_KEY).
  • Automatic retries, the build method, your package repository's name, schedules, and any Dev, UAT or other environments.

What a blueprint never holds

Settings values, passwords, keys, links to your accounts, team members, and the addresses of your servers or databases. A blueprint is safe to keep in a repository or send to a colleague. When it's used, the values are filled in again for the new project.

Export one

On a project's Dashboard, choose Blueprint. You see the setup drawn as a flow, a list of what the file carries, and the file itself. Then:

  • Download saves your-app.blueprint.json.
  • Save to Blueprints keeps it in your workspace's library (Projects, then Blueprints).
  • Create a project from this opens a new project with everything filled in.

Turn off Include the repository to make a recipe for any repository.

Create a project from one

From New project, choose Start from a file or copy another project's setup. Upload or paste a file, pick a saved blueprint, or copy a project. Then check three things: the repository, where it runs, and the web address. The right side shows what will be set up, in three groups: as in the blueprint, adjusted (with the reason) and left for you.

Create project doesn't deploy anything. Your code is checked first (about a minute), then the blueprint's choices are applied, and you land on Settings: fill in the values, then press Launch as usual.

When a choice can't be kept, you are told why and what was chosen instead. Some examples:

  • The repository has no service with the blueprint's name: a service of the same kind is used.
  • The cloud is different: the same plan is used on the new cloud (AWS App Runner becomes Google Cloud Run, for example).
  • The rule asks for a password: you set it, because blueprints never carry one.

Write or edit one

A blueprint is plain JSON with a published schema, so editors like VS Code complete fields and underline mistakes as you type. Add this first line:

"$schema": "https://thedploy.com/schemas/blueprint-1.json"

You can also edit one in the app (Projects, then Blueprints, then Edit), with a form for the common fields and the JSON beside it. A mistake is shown with its line and how to fix it, for example: "extars is not a blueprint field. Did you mean extras?" Fields starting with x- are yours for notes and are ignored.

A small blueprint:

{
  "$schema": "https://thedploy.com/schemas/blueprint-1.json",
  "blueprint": 1,
  "name": "Shop API",
  "source": { "repository": "acme/shop", "branch": "main", "service": { "name": "api", "path": "apps/api" } },
  "hosting": { "plan": "growth", "database": { "engine": "postgres", "standby": true }, "cache": { "engine": "redis" } },
  "extras": ["uptime", "alerts", "monitoring", "logging", "backups"],
  "web_address": { "type": "custom", "domain": "acme.com", "app": "api" },
  "who_can_open": { "mode": "networks", "groups": ["Office"] },
  "settings": [{ "key": "SECRET_KEY", "generate": "secret" }, { "key": "STRIPE_SECRET_KEY" }]
}