Contributing

Thanks for wanting to help out - it's genuinely appreciated! 🙌

This repo compiles Portainer app templates from lots of sources into a single templates.json. Most contributions are either adding apps to that list, or improving the tooling around it.

Adding your app

Tip

📖 New to Portainer templates? Follow the full guide: Creating a Template
It walks through every field with examples, how to test your template, and a checklist to go through before you submit.

Tip

Templates added into any of our sources will be automatically pulled into this repo nightly. For example, you can submit self-hosted apps to portainer-templates-extras, and they'll be included in this repo once merged.

The easiest way is to keep the template in your own repo. We pull it in every day, so you can update it whenever you like, without needing another PR here.

Add a portainer-template.json file to your repo, containing a single template
Add a row to the bottom of sources.csv with a name, the raw URL, your repo URL, and app

my_app, https://raw.githubusercontent.com/you/my-app/main/portainer-template.json, https://github.com/you/my-app/, app

Your template needs a type, title, description, and either an image (for a container) or a repository pointing at a compose file (for a stack). It's also worth including a logo, categories, platform, restart_policy and a short note on getting started, plus whatever ports, volumes and env your app needs. The full format is in Portainer's docs, but here's an example:

{
  "type": 1,
  "title": "My App",
  "description": "What it does, in a sentence or two.",
  "categories": ["Productivity"],
  "platform": "linux",
  "logo": "https://raw.githubusercontent.com/you/my-app/main/logo.png",
  "image": "ghcr.io/you/my-app:latest",
  "restart_policy": "unless-stopped",
  "ports": ["8080:8080/tcp"],
  "volumes": [{ "container": "/app/data" }],
  "env": [{ "name": "TZ", "label": "Timezone", "default": "UTC" }],
  "note": "Anything people need to know to get it running."
}

Rather not host it yourself? You can drop a JSON file into sources/local/ instead (and any compose file into sources/stacks/), but you'll need a new PR here each time you want to change it.

Adding a template list

If you maintain a list covering lots of apps, add it to sources.csv in the same way, but with collection at the end instead of app.

Fixing a broken template

Most apps appear in several sources, and we publish whichever copy comes from the highest-priority source. Sometimes that copy is the bad one - a dead image, a tag that no longer exists, a missing port. Rather than copying the template into sources/local/, add an entry to overrides.json and point it at a source that has a good copy:

{
  "title": "Jenkins",
  "prefer": "mikestraney_templates",
  "reason": "Portainer's copy pins the retired lts-jdk11 tag",
  "updated": "2026-09-23"
}

title is matched the same way duplicates are deduped, so case and punctuation don't matter. Add "type": 3 if the app exists as both a container and a stack. prefer is a source name exactly as it appears in sources.csv.

If no source has a working copy, leave prefer out and record what's wrong instead. The note is published alongside templates.json so the website can flag it:

{
  "title": "Elasticsearch",
  "status": "broken",
  "note": "No source has a working image - upstream publishes no rolling latest tag.",
  "updated": "2026-09-23"
}

status is one of ok, unmaintained or broken. As a last resort you can write the template out into sources/local/ yourself, since local sources beat every external one - but only when nothing upstream works, because anything in there becomes ours to maintain.

The build warns when an override stops doing anything - the app disappeared, the preferred source no longer carries it, or normal priority already picks it - so stale entries are easy to spot and delete.

Important

If the app itself is broken - a bug in the software rather than the template - please raise it with that project upstream. This repo only compiles templates, so an upstream fix flows through on the next build either way. But if our published template picks a bad copy of a working app, that one's on us: use overrides.json as above.

Improving the tooling, docs or site

Fixes and improvements to the lib/ scripts, the workflows, this documentation, or the website are all very welcome - just open a PR.

Testing your changes

The following checks will run automatically on opened PRs, but you can check this locally yourself before submitting:

make install_requirements   # one-time: install deps
make validate_sources       # validate your templates, stacks + sources list
make                        # or build the whole thing end-to-end

A few notes

New to open source? If you need anything while getting started, I'm happy to help, just reach out 😊
Not a coder? You can still help by reporting bugs, improving the docs, or sponsoring the project 💖
And of coure, please be kind - we follow the Contributor Covenant

Thanks again - see you in the PRs! ✨

5.9 KiB Raw Permalink Blame History