Template best practices
Make templates reliable to deploy and clear for teammates: Git hosts, names, secrets, builders, and marketplace text.
These habits keep Deploy from template smooth and make Community listings trustworthy.
Put a supported Git host on every app
Only GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea are included when someone deploys. Anything else is skipped with a warning. If every app is skipped, the template cannot deploy at all.
Before you publish, run a test deploy in a scratch Application and check that the service count matches what you expect.
Use short, stable service names
Names appear in URLs, on-server app names, and placeholders like {{ api.DATABASE_URL }}. Avoid spaces. If a name is already used globally, deploy may add a suffix, so unique names reduce confusion.
One copy of each secret
Store passwords or connection strings on the database service (or one canonical service) and reference them from apps. You update one place when something rotates.
Match build style to the repo
Build packs work for many repositories. Switch to Dockerfile, Nixpacks, Static build, Railpack, or Heroku build packs when the repo needs it so the first deploy succeeds without manual fixes.
Expect databases before apps
The platform starts database services before apps and Docker services. Point apps at database variables that will exist by then.
Test the full path before publishing
Create a test Application, add a new Environment on a free server, deploy, then read Logs for each Service. Fix the template, then Publish.
Review screen totals are hints
The Review step shows rough resource totals. They do not reserve capacity or predict cost.
Write for people who do not know your repo
Publishing needs enough Template Overview text and Short Description length (see Publish a template). Say what runs, what integrations to connect first, and any manual steps after deploy.
Security
- Do not paste production secrets into Community descriptions or Template Overview text.
- Prefer organisation Git and registry connections over long-lived tokens in the template.
- Anyone in your tenant who can read the template may see variable values allowed by their role.