Skip to content
NebulaCtrldocs
Guides

Install and share templates

Install a built-in, community or organization template into a project, save a project as a template, and share or contribute one.

A template is one YAML file that creates a set of services, with the questions to answer at install time. Install one to get running services without wiring each one by hand, or write one so that others can. The template file reference lists every field.

Before you begin

  • To install into an existing project, you need the deployer role or higher. To install into a new project, you need the admin role.
  • To deploy the installed services, the environment you install into needs a cluster. See Connect a cluster.

Install a template

  1. Open Templates. The page has three sections: Built-in, which ships with your NebulaCtrl version, Community, and Your organization.
  2. Open a template to read its page, and select Install. A community template, or one from a URL, shows a warning: Written outside NebulaCtrl, so check the images it runs in its source before installing. Read the images and variables it lists first.
  3. Under the target control, choose New project and enter a Project name, or choose Existing project and pick one.
  4. Choose an Environment. With one, the dialog stages the first deploy of every service. With None, it only creates the services: no domains and no first deploys.
  5. Answer the inputs. A required input must be filled. A secret input shows a masked field.
  6. To change a service's name in the project, open Advanced: rename services.
  7. Select Install.

The result lists each service and each domain. A domain reports its own outcome, so a failed domain does not undo the services.

The install is atomic for the project, services, processes, volumes and variables: one transaction writes all of it or none. A template's variables are written to every environment of the project, and secret(N) draws a separate value for each environment. A service whose slug the project already uses fails the install with a 409 that says which service to rename.

Nothing builds or deploys until you apply the staged change set. With an environment, the first deploys of the services are staged in that environment, databases first. On a protected environment, applying the change set waits for an approval like any other deploy. See Change sets and approvals.

Verify

The services appear on the canvas, marked as staged. In the staged bar, select Deploy N changes, where N is the number of staged changes. On a protected environment the button reads Request approval. The review dialog lists what will happen, and the same button applies it. Each service then goes through deployment and becomes healthy.

Install from a URL

A template does not have to be saved anywhere. Select Install from URL on the Templates page, enter the link in Template URL, and select Preview. The console accepts an https:// link whose path ends in .yaml or .yml. A GitHub link of the form https://github.com/OWNER/REPO/blob/REF/PATH works, where REF is one path segment, so a branch name that contains / does not.

NebulaCtrl previews the file and lists its problems. Selecting Install reads the URL again, so the installed content is what the URL serves at that moment.

You can share the same preview as a link:

https://CONTROL_PLANE/ORGANIZATION/templates?install=TEMPLATE_URL

CONTROL_PLANE is your control plane's address, ORGANIZATION is your organization's slug, and TEMPLATE_URL is an https:// URL to the YAML file. Opening the link shows the preview. Nothing is saved to your organization.

Save a project as a template

To turn something you already run into a template:

  1. Right-click the project's canvas, or the project in the project list, and select Save as template….
  2. Under From environment, pick the environment to export. The dialog tags each service as exported, a database, a warning or skipped.
  3. Select Open in editor, check the file, and select Save template.

The saved template appears under Your organization.

The export covers the services, processes, volumes, variables and domains of the environment. It skips a proxy service, a service built from a private Git connection and a service that pulls through a private registry credential, and warns about each. It does not export environment or project variables, file mounts, release commands or deploy-after lists. A secret variable becomes a required secret input. A domain becomes an input named <SERVICE>_HOSTNAME, or <SERVICE>_<PROCESS>_HOSTNAME when several processes of one service have a domain.

Check the exported file before you share it. An image with no release in the environment is exported as <repository>:latest, so pin its tag.

Write a template

To write a template, open New template on the Templates page, or create a file by hand. The editor shows Checking… and then either each problem as Line N: path: message or ok (NAME, N services). It validates 400 ms after your last keystroke. It does not check the file name against the slug. Run nebula template validate for that, as described in the reference.

Saving from the console stores the YAML you see. A template you save with the API from a URL (POST /api/v1/templates with url) remembers that URL, and its page offers Refresh from URL. A template saved from the console has no URL to refresh.

On an organization template's page, Edit… changes it, Copy install link shares it when it has a URL, and Delete template removes it after a second click.

Contribute a template

Contribute a template to the community catalogue with a pull request:

  1. Fork nebulactrl/nebula-templates.
  2. Add templates/SLUG.yaml, where SLUG equals the template's slug.
  3. Run nebula template validate templates/SLUG.yaml.
  4. Open a pull request.

Every NebulaCtrl installation reads the main branch about once an hour, and Refresh in the Community section reads it sooner. Only templates/SLUG.yaml files count: a file with another extension is ignored. A file that fails validation, is larger than 256 KiB, or has a slug that differs from its file name is skipped silently, as is a template whose slug equals a built-in template's. The built-in template wins.

To turn off the community catalogue, or to read your own fork, set --community-templates or --community-templates-repo on the control plane. See Configuration.

Next steps

Import a Docker Compose file

Review a repository's Compose files in four steps and stage their services, databases, secrets and wiring in one change set.

Configure a service from its repository

Add a nebula.toml to a service's build context so each build reads its processes, variables and build settings from Git, and see the console follow it.

On this page

Before you beginInstall a templateVerifyInstall from a URLSave a project as a templateWrite a templateContribute a templateNext steps