Dockyard

A set of 700+ Portainer app templates (v3 format), plus a browsable static website ("Dockyard") for finding them.

Everything is generated from a single source of truth — one YAML file per app in apps/ — by a small Python CLI. That CLI produces two things:

1. `templates.json` — paste its raw URL into Portainer's *Settings → App Templates → URL* to get one-click deploys for every app in the gallery.
2. `docs/` — the Dockyard website: cards with logo, description, category and links, searchable and filterable.

Using the feed in Portainer

1. Open Portainer and go to Settings → App Templates.
2. Paste this URL into the URL field:

   https://cdn.jsdelivr.net/gh/bauerpawel/DOCKYARD@main/templates.json

1. Save.
2. Open App Templates in the sidebar (under an environment) — every app below is now one click away from deployment.

Requires a Portainer version that supports v3 app templates.

See local app setup for Open WebUI, Ollama, Backrest, Pocket ID, BentoPDF, Pangolin, Appwrite, Plane with RustFS and the Hoarder-to-Karakeep migration. These templates use pinned images; supply required secrets and deployment settings before starting a stack.

The 2FAuth–Dispatcharr setup guide covers twenty more applications, including Hoppscotch, Rybbit, Sure and Bar Assistant, with pinned images, local Compose stacks and first-start instructions.

The Dockhand–Cleanuparr setup guide adds monitoring, networking, support and media applications, including ERPNext and ZITADEL, with initialization steps and host-access requirements.

The Garage–Workout.cool setup guide covers another twenty applications for storage, certificates, documents, collaboration and development, including initialization commands and persistent-data requirements.

The Spoolman–Temporal setup guide covers filament tracking, scheduling, collaboration, media and workflow infrastructure. It details the Cal.diy compatibility image, AMD64 requirements and service initialization.

The feed is served through jsDelivr's CDN rather than raw.githubusercontent.com directly, for faster, more reliable loading worldwide. The scheduled workflows (below) purge jsDelivr's cache after every rebuild, so Portainer always sees the latest templates.json within seconds of a change landing on main.

The website

Browse the same catalog at https://dockyard.kim1.ovh — search by name, filter by category, and click any app's name/logo/description to expand the full description. Each card links to the app's Docker Hub page and (where known) its own source/homepage.

The interface is available in English, Polish, German and French. It follows the browser's language, the switcher in the header changes it, and ?lang=pl (or de, fr) links straight to a version. The strings live in site_src/i18n.json; app descriptions stay in English. The build also writes robots.txt, sitemap.xml and the search-engine metadata (canonical URL, hreflang alternates, Open Graph card, JSON-LD) for the domain named in site_src/CNAME.

MCP server for AI agents

The catalog is also available to AI agents through an MCP server:

https://dockyard.kim1.ovh/mcp

With it, Claude, Codex, Grok, Gemini CLI, Cursor, VS Code and other MCP clients can search the apps (list_apps), read an app's details (get_app) and prepare a deployment plan (prepare_deploy). The server only describes apps and builds the plan: it has no access to your Docker or Portainer, and the agent deploys on your machine after you confirm.

Add it to Claude Code with:

claude mcp add --scope user --transport http dockyard https://dockyard.kim1.ovh/mcp

For other clients, open the address in a browser. It shows setup instructions in English, Polish, German and French.

Quick start

Requires Python 3.14+.

The fastest way to (re)build everything from apps/ and stacks/ — sets up .venv if needed, builds templates.json + docs/, and validates the result. This does not talk to Docker Hub (see Keeping metadata fresh below):

run.bat                 # Windows

./run.sh # Linux / macOS

Extra arguments are passed through to gallery build, e.g. run.bat --repo-url https://github.com/bauerpawel/DOCKYARD.

The default URL comes from repository.json. Forks should update that file or use --repo-url; a successful build saves the override there so the feed, website and MCP agree on repository identity. Placeholder OWNER/REPO URLs are rejected.

For manual/step-by-step control:

python -m venv .venv

.venv/Scripts/activate # or: source .venv/bin/activate on Linux/macOS pip install -e ".[dev]"

python -m gallery fetch-metadata # refresh Docker Hub descriptions (cache/dockerhub.json) python -m gallery build # -> templates.json + docs/ python -m gallery validate # check templates.json against Portainer's v3 schema pytest # run the test suite

Open docs/index.html directly in a browser to preview the site locally.

Hosting metadata also comes from site_src/: edit site_src/CNAME for a custom domain, or remove it for the default Pages domain. An optional site_src/.nojekyll is copied as well. site_src/MCP_URL holds the address of the MCP server that the site advertises under the feed URL; change it to your own server or remove the file to leave the note out.

Builds validate app YAML against schema/app_schema.json and the generated feed against the Portainer schema before publishing. Rendering and asset copying happen in a temporary directory. A failed publication restores the previous feed, site and repository configuration; a failed rollback preserves the backup directory and reports its path.

The full integration suite also uses PHP 8.2+, Node.js 18+ and the Docker Compose CLI. Compose tests run config only and require no Docker daemon or running containers.

Security checks

Install the audit tool with pip install -e ".[dev,audit]". In an activated virtual environment:

python -m pip freeze --exclude-editable > .venv/audit-requirements.txt

python -m pip_audit -r .venv/audit-requirements.txt --no-deps --disable-pip --strict --progress-spinner off

The snapshot includes installed transitive and development dependencies. CI installs Python packages from requirements/build.txt and requirements/requirements-dev.txt, locked with hashes and a seven-day cooldown for new releases; after changing dependencies in pyproject.toml, rerun the uv pip compile command in each file's header. That command keeps existing pins, so add --upgrade (or --upgrade-package ) to raise locked versions, for example to clear an audit finding. The CI checks run tests, build/validation, and a dependency audit on pushes, pull requests, and every Monday. Dependabot checks Python packages, Composer dependencies and pinned GitHub Actions weekly. See SECURITY_AUDIT.md for the audit scope and findings.

The MCP YAML parser is bundled under mcp/vendor/ with its licenses and mcp/composer.lock. Run composer audit --working-dir=mcp --locked --no-dev to check PHP dependencies. To update them, run composer update --working-dir=mcp --no-dev and commit the lockfile together with mcp/vendor/. Dependabot's Composer PRs change only the lockfile, so run that command on their branch before merging: deploy/refresh.php refuses a release whose mcp/vendor/ does not match the lock, and the refresh tests fail.

MCP plans run on the user's machine, so the server only hands out what it can verify. Stackfiles from other repositories are served at the commit and SHA-256 pinned in stacks.lock.json; an upstream change reaches plans only after review and python -m gallery pin-stacks --update. Compose is checked against an allowlist: host paths outside the data directories, build, external resources, unknown keys and variables the plan does not set need allow_privileged, and a stack that substitutes PORTAINER_* is always blocked.

Local stacks under stacks/ require nonempty passwords supplied through the app's environment fields in Portainer or a local .env file. For MCP plans, use local_secrets and replace CHANGEME locally. Keep the database password already used by an existing volume when redeploying; changing the .env value alone does not rotate database credentials. n8n uses its owner account setup in the web UI, not the removed N8N_BASIC_AUTH_* settings.

Keeping metadata fresh

gallery fetch-metadata is the only command that talks to Docker Hub. It's deliberately kept out of run.bat/run.sh's default flow so a routine rebuild never risks Docker Hub's anonymous rate limit - gallery build always reads whatever is already cached in cache/dockerhub.json.

Two scheduled GitHub Actions workflows handle both cadences automatically (see .github/workflows/):

• `build.yml` - runs on every push to main (so a newly added app template goes live right away, and any direct change to templates.json still gets its jsDelivr cache purged even if it didn't go through apps//stacks/), plus every Saturday as a safety net. Rebuilds templates.json + docs/, commits if anything changed, and purges jsDelivr's cache for templates.json and stacks.lock.json. Also runnable on demand from the Actions tab.
• `refresh-dockerhub.yml` - on the 1st of each month (the closest calendar-cron equivalent to "every 30 days"), refreshes cache/dockerhub.json, rebuilds, and commits.

Both build with a read-only token and the hash-pinned packages in requirements/build.txt. A separate job (publish-generated.yml) runs no Python packages and commits only the generated files. main requires the test (3.14) and audit checks, so the job pushes the commit to a temporary publish/* branch, runs the tests there, records the passed jobs as commit statuses and only then moves main to that commit.

Run python -m gallery fetch-metadata locally any time you want an out-of-band refresh.

Adding a new app

See CONTRIBUTING.md for the full guide (field reference, category list, and how to source a trustworthy logo/website/image). Short version:

python -m gallery new my-app --type container   # or --type compose

This scaffolds apps/my-app.yaml. Fill in the fields:

name: My App

slug: my-app category: Utilities type: container # container | compose image: namespace/my-app:latest # required - must be a real Docker Hub image compose: null # required for type=compose instead, e.g. stacks/my-app/docker-compose.yml description: null # null = auto-fetch from Docker Hub; or write your own text note: null # optional - Portainer deployment instructions; HTML supported logo: https://.../my-app.png # required website: https://github.com/... # optional - the app's own site or source repo network: null # optional, container only - Docker network to attach to, e.g. host command: null # optional, container only - override the container's command privileged: null # optiona