← Documentation

Templates & duplication

Environment drift is the problem where staging slowly stops resembling production, and reproducing a bug means rebuilding a project from memory. Templates and duplication exist to make "give me another one of those" a single action.

What a template is

A template is a project's shape, saved without its contents. It records what a project is made of — which apps, pointing at which images or repositories, with which ports, resources and variables; which managed services, at which sizes; how configuration and secrets are laid out — and it records none of the running state. No pods, no database rows, no accumulated logs.

The distinction that matters: a template is not a backup and it is not a snapshot. Spawning a project from one does not restore data. It creates a new project with the same structure, whose databases start empty and whose apps deploy fresh. If what you want is your data back, a template is the wrong tool and a database backup is the right one.

It is also a point-in-time capture, not a live link. A template taken today does not change when the project it came from changes, and projects spawned from it do not track it afterwards. That is deliberate — a template that mutates underneath you is not a template — but it means a template you rely on needs re-taking when the original moves on.

The unit is a whole project rather than a single app, because the useful thing to reproduce is rarely one service. It is a service plus the database it talks to plus the configuration that connects them.

Two related things

Duplicate copies a live project into a new one—right now, from the project you're looking at.

Save as template captures that same shape as a reusable template stored at the organization level. You can spawn new projects from a template whenever you need one, long after the original has changed.

Use duplication when you want a copy today. Use a template when you want a repeatable starting point. Both produce a real, independent project: the copy shares nothing with the original, so a migration you run in it cannot touch the source's database.

Duplicating a project

  1. Open the project and choose Duplicate.
  2. Name the new project and pick which server it should land on—it does not have to be the one the source runs on.
  3. Choose what to carry over: apps, configs and secrets, services, and domains.
  4. Confirm.

Kaja creates the new project and recreates everything you selected inside it.

What to think about before you confirm

  • Secrets. Duplication can copy real credentials into the new project. The confirmation step tells you exactly which secrets are involved—read it. Copying a production key into a staging environment is easy to do by accident and hard to undo.
  • Services. Managed services are recreated as new instances with their own storage and credentials. The copy does not share a database with the original.
  • Domains. A generated hostname is issued fresh for the copy. A custom domain can only point at one place, so it stays with the original.
  • Auto-deploy. Decide whether the copy should redeploy on push. A duplicate that shares a repo with the original will otherwise rebuild every time that repo changes.

Templates

Templates live at the organization level, not inside a single project, so any project in the organization can be spawned from one. Create a template from a project you're happy with, then use it as the starting point for new environments.

Because a template is captured at a point in time, it does not track later changes to the project it came from. If the source project moves on, create a new template from it.

Pausing a project

Related but different: pause scales a project's apps to zero without deleting anything, so a project you're not using stops consuming resources while keeping its configuration. Resume it when you need it again. Pausing is manual—Kaja will not pause a project on your behalf.

Next steps