Create a template

You can create a new template from the templates page in your team dashboard, or from the templates page in a project.

You can create the template using the visual or code editor, and configure the template's settings on the template edit page.

The Northflank editor includes code hints, autocompletion, and error checking to help you include required properties in the correct format.

You can create and edit a template using either the visual editor to drag and drop nodes, or by editing the template code directly. You can switch between these views at any point when editing a template.

Create a template using the visual editor

The visual editor allows you to drag and drop nodes in the order you want them to run.

Nodes must be nested in workflows, which define whether nodes contained run in sequence (sequential), or at the same time (parallel). Workflow nodes can be nested within other workflow nodes. You can click the button in the workflow node to switch between parallel and sequential workflows.

To add a node, find the relevant node from the list, or use the search box, and drag the node into your workflow. If a node is inserted into a sequential workflow, it will be placed before, between, or after other nodes depending on where it is dropped, with arrows showing the sequence the template will run in. Nodes dropped into a parallel workflow will be added without any sequence, as they will be executed simultaneously. You can drag and drop nodes to re-order them, or move them into and out of workflows.

Click on an individual node to edit that specific node. You can configure a node using the form, or switch to code to directly edit the JSON for the individual node. Editing the code directly is particularly useful to paste in resource specifications from your existing projects, or other sources.

Click save node to finish editing an individual node, cancel to discard your changes, or delete node to remove it.

Click create template or save template to save your template.

Create a template using the code editor

Template code consists of JSON defining resources and actions to be performed in workflows.

You can enter the content of your template using the Northflank code editor by selecting code. The editor includes code hints, autocompletion, and error checking to help you include required properties in the correct format.

Configure template settings

You can set the name and description for your template, and configure how your template will behave in the settings view.

Every node for a project-level resource must have a project context. You can either set the project context directly in the resource node, or the node can inherit the project context from a parent workflow. You can create and update resources across multiple projects by setting different contexts for workflows or nodes.

Learn more about setting project contexts.

You can enable run a template automatically so that any changes made to the template will trigger a template run, whether it's updated in the Northflank UI, via the API, or changed in the Git repository (if GitOps is enabled).

This is convenient if you want to manage your resources via templates, as triggering a run automatically will mean your resources will be updated to reflect the template specifications on change.

You can enable GitOps to sync the template with a Git repository. You can make changes to your template by committing changes to it in the repository or by editing it on Northflank, and the changes will be propagated to the other platform automatically. This allows you to maintain your templates alongside your codebase, or in a separate infrastructure repository.

Enable GitOps and select the repository and branch that contains, or will contain, the template code. Enter the path to the template relative to the repository root. For example /template.json will look for a file called template.json in the repository root, while /platform/backend.json will look for a file called backend.json in the directory platform.

If a template file already exists at the path, it will be loaded into the editor. If no file exists, one will be created with the template specification defined in the editor.

It is not necessary, but it is recommended, to save the template file with the format json so it can be recognised by IDEs and text editors.

Learn more about GitOps on Northflank.

You can choose how a template will behave if it receives more than one request to run at the same time, or receives a request to run while a run is still in progress.

• Allow (default): multiple template runs can be executed in parallel, with no restrictions
• Queue: each time a template run is triggered it will be added to a queue, and runs will be executed sequentially in order of creation
• Forbid: if a template is currently pending or running any run requests will be ignored

You may want to queue or forbid simultaneous runs to ensure that resources are not updated with conflicting configurations.

You should not include any secrets, such as API keys, passwords, or other sensitive data in your template. Instead, you should define argument keys in your template and provide the values in argument overrides, which are stored securely on the Northflank platform, encrypted at rest.

You can configure argument overrides for a template which will override any arguments with the same key. If the key specified in the overrides object does not exist in the arguments object, it will be inserted.

Secret file encoding

Generally, secret files should be provided as a base64-encoded string. Secret file content provided as plain text via the UI will be converted to base64 when it is stored securely on the Northflank platform.

You can specify how Northflank will handle the data value for your secret file using the encoding field when it is mounted to the container. If you specify utf-8, Northflank will decode base64 content to utf-8. For example, you can use this to provide JSON, YAML, or other configuration files as a base64-encoded string, which can then be decoded for use in your container.

If you select base64 encoding, Northflank will mount the file as base64 content without decoding it.

Provide secret files in templates

You can provide secret files in service, job, and secret group resource nodes, in the relevant field for the resource in the template specification.

To use arguments, references, or functions in a secret file you must provide the content as a plaintext string so that they will resolve correctly when the template runs. You can then wrap the content in the toBase64 function to encode the content as base64. For example:

{
  "files": {
    "/config": {
      "data": "${fn.toBase64(args.CONFIG_SECRET)}",
      "encoding": "utf-8"
    }
  }
}

The argument or reference will be evaluated and the content of the secret file will be saved as base64. Northflank will then decode the data content to utf-8 when it is mounted to the container.

The simplest way to start writing a template is to get the template specification for your existing resources or entire projects.

Once you have your resource or project correctly configured and running you can copy the specification, paste it into a new template, and modify and add nodes.

View project template

Click the project template button in the project header to get the template for an entire project. You can switch between viewing the template code and the visual representation of the project, and view the specification for individual resources by clicking on a node in the visual editor.

View resource specification

To view the specification for individual resources, such as services, addons, jobs you can click the options button in the resource's header.

Select view specification and ensure the view is on template code. Toggle between node only to copy the specification into an existing template, or full template which will give you a full template specification including the resource.

There are two ways to access your templates in the Northflank UI, either from your team dashboard, or from within a project.

Your team templates page will display all templates created within your team, regardless of any projects they may be related to. The template page within a project will only show templates that create or reference that project.

These separate views are only to make it easier to navigate to relevant templates as all templates are stored on the team.