Add a template

​

The two files

internal/catalog/manifests/<id>/template.yaml
internal/catalog/manifests/<id>/compose.yaml

​

Worked example

id: acme-notes
name: Acme Notes
description: A self-hosted notes app with sharing and full text search. Runs on SQLite in one container. On first open, the setup page asks you to create the admin login.
icon: book
category: Productivity
documentation_url: https://notes.acme.example/docs
source_repo: https://github.com/acme/notes
license: AGPL-3.0-only
license_class: network-copyleft
license_url: https://github.com/acme/notes/blob/main/LICENSE
hosted_use: unknown
listing:
  by: community
status: active
recommended_memory_bytes: 268435456
first_run:
  - Open the app and create the admin account on the setup page.
env:
  - key: TZ
    label: Time zone
    description: IANA time zone for dates and logs.
    default: Etc/UTC
domains:
  - service: notes
    port: 8080
    description: Public address of Acme Notes.
healthcheck:
  service: notes
  port: 8080
  path: /

services:
  notes:
    image: ghcr.io/acme/notes:1.4.2
    ports: ["8080"]
    environment:
      TZ: ${TZ}
      SECRET_KEY: $SERVICE_PASSWORD_64_NOTESKEY
    volumes:
      - notes_data:/data
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080/ || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 10
      start_period: 30s

​

Required fields

​

Eligibility rules

• Exact version tag. 1.4.2, not latest, stable, edge, main, nightly, beta, rc or a bare major such as 16. A tag like 1.4 needs a maintainer exception.
• Image source. The image comes from the upstream project’s own registry namespace (matching source_repo), a Docker Official Image, or an allowed rebuilder (LinuxServer.io). Anything else needs a maintainer exception and cannot be a vendor listing.
• No digest in the file. CI resolves the digest and records it in a generated lock file.
• Healthcheck present, and it must translate into a real probe.
• No privileged containers, host network, host PID, added capabilities, device passthrough or container sockets (the same compose guard every deploy uses).
• Named volumes only. No bind mounts, and each service keeps its own volumes.
• No download or install at start. An entrypoint or command that runs curl, wget, git clone, pip install, npm install, apk add or apt-get is rejected unless a maintainer grants an exception with a reason.
• Published database ports need a generated credential, or no host port at all.
• No telemetry opt-out secrets or real credentials in the files. Nothing secret goes in a template.
• Arm64: say in the pull request whether the image publishes linux/arm64. The catalog scan records it; you do not need to claim it in the file.
• Maintainer contact: put a way to reach you (GitHub handle) in the pull request.

​

What CI checks

1. The loader and submission rules above.
2. The image tag resolves and lists the platforms it claims, and is under the size limit.
3. A vulnerability and secret scan of the image, joined with the CISA known-exploited list. A known-exploited hit or an unallowed secret blocks the pull request. A critical issue with a fix available is a warning.
4. A signature and attestation lookup, recorded when present and never required.
5. A smoke run: every service starts and stays up, and the declared health path answers.

​

What Verified means

​

Vendors

listing:
  by: vendor
  vendor_org: acme

​

Check it locally

scripts/template-lint.sh <id>            # validate the files and the submission rules
scripts/template-lint.sh <id> --smoke    # also start it under Docker and check it stays up

​

Updates and takedowns