publish-resyndeo-plugin

Publish a Resyndeo plugin

This skill packages a local app as a private Resyndeo plugin and deploys it to the user's own fleet. The CLI handles the full build→import→publish pipeline; this skill drives that workflow step by step.

Reference material (pull when you need detail):

• references/rail-reference.md — full plugin.yaml field guide
• references/capability-kinds.md — backing-service capability kinds and the env vars they inject
• examples/http-service/ — minimal HTTP server plugin
• examples/postgres-api/ — plugin that consumes a Postgres backing service

---

Step 1 — Preconditions

Verify the environment before touching any files.

resyndeo whoami                  # must print an email; if not → resyndeo login
docker info                      # must succeed; if not, start Docker
resyndeo cluster list            # must list ≥1 cluster; if not → resyndeo cluster install

All three must pass before continuing.

---

Step 2 — Scaffold

plugin init writes plugin.yaml, Dockerfile, and .dockerignore with sane defaults. It refuses to run only when plugin.yaml already exists — it does not guard Dockerfile/.dockerignore. So if plugin.yaml is absent but the directory already has a Dockerfile (common — you're packaging an app you've already built), init will silently overwrite that Dockerfile with the generic scaffold.

Check what's already there before running it:

ls plugin.yaml Dockerfile .dockerignore 2>/dev/null

• No plugin.yaml and no Dockerfile you care about → safe to scaffold:

  resyndeo plugin init <slug>   # e.g. resyndeo plugin init my-api
  

• A Dockerfile (or .dockerignore) you want to keep → do not run init; it would clobber them. Hand-write plugin.yaml instead (schema in references/rail-reference.md) and leave your Dockerfile untouched.
• plugin.yaml already exists → init errors and changes nothing; just edit the existing plugin.yaml.

Then edit plugin.yaml using the actual app's values:

• Set workload.ports[].port to the port the app listens on (e.g. 8080).
• If the app needs a backing service (Postgres, Redis, etc.), add capabilities.consumes — see references/capability-kinds.md for the list of valid kind values and the env vars each one injects.
• Fill in metadata.title, metadata.description (required — backend rejects empty), metadata.category, and metadata.version.

Do not set workload.image — the publish command computes and injects it.

See references/rail-reference.md for the full field guide.

---

Step 3 — Author the Dockerfile and app

• The app must listen on the exact port declared in workload.ports[].port.
• When capabilities.consumes is declared, the platform injects connection env vars once both plugins are deployed (e.g. DATABASE_URL for Postgres). The app must read those env-var names — do not hard-code connection strings.
• The Dockerfile must produce a runnable image (single binary or interpreter + app). See examples/ for minimal working examples.
• Do not add workload.image to plugin.yaml — publish owns that field.

---

Step 4 — Fast local build check

Before publishing, verify the image builds cleanly:

docker build -t tmp-check .
# Optionally smoke-test it locally:
docker run --rm -p 8080:8080 tmp-check

Fail early here rather than after publish.

---

Step 5 — Publish and deploy

resyndeo plugin publish <dir> --deploy
# e.g. resyndeo plugin publish . --deploy

The CLI:

1. Reads plugin.yaml, extracts slug + version.
2. Computes a deterministic local image tag (owner-prefix + slug + version).
3. Runs docker build with that tag.
4. Imports the image into every local k3d cluster with k3d image import (so imagePullPolicy: IfNotPresent resolves without a registry).
5. Injects workload.image into the rail and POSTs it to the backend, which registers it as a private catalog plugin owned by you.
6. With --deploy: immediately installs the plugin to your cluster.

Expected output:

→ building resyndeo-local/<prefix>-<slug>:<version>...
✓ built resyndeo-local/<prefix>-<slug>:<version>
✓ imported into 1 cluster(s)
✓ published <slug> → your catalog (private)
✓ <slug> deploying

---

Step 6 — Verify and iterate

resyndeo plugin status <slug>     # → "installed" once the pod is Running

To update: bump metadata.version in plugin.yaml (the same version will not roll a running pod), then re-run resyndeo plugin publish . --deploy.

To remove:

resyndeo plugin delete <slug>

---

Known limitation (v1)

plugin publish imports the image into clusters on the local machine only. A remote cluster added later, or a second machine, will see ImagePullBackOff because it cannot pull a local image. Workaround: re-publish from that machine, or push to a registry the remote cluster can reach (future feature).