First Plugin Upload

This guide walks you through uploading your first PF4J plugin to Plugwerk.

Prerequisites

• A running Plugwerk instance (see Quickstart)
• A PF4J plugin — either a JAR or a ZIP archive (JAR + lib/ dependencies)

Plugin Descriptor

Plugwerk reads plugin metadata from the standard Java MANIFEST.MF inside the plugin JAR. Required attributes:

| Attribute | Purpose | | ---------------- | ----------------------------- | | Plugin-Id | Unique plugin identifier | | Plugin-Version | SemVer version (e.g. 1.0.0) |

See Plugin Descriptor for the full attribute reference.

Supported Formats

Plugwerk accepts two PF4J plugin formats:

• JAR — a single JAR file with a valid MANIFEST.MF
• ZIP — a ZIP archive containing the plugin JAR at the root and dependencies in a lib/ directory

Both formats are standard PF4J packaging. See Packaging for build examples.

Upload Steps

1. Navigate to your namespace

   Open the Plugwerk Web UI and select the namespace where you want to upload the plugin.

2. Upload the plugin

   Click "Upload" in the top navigation and select your plugin JAR or ZIP file.

   Plugwerk will:

   • Parse the MANIFEST.MF descriptor
   • Validate the plugin ID and version
   • Compute a SHA-256 checksum
   • Create the plugin entry (if new) and a release

3. Review and publish the release

   The behavior depends on the namespace configuration:

   • Namespaces with review enabled (default): New releases require approval by a namespace admin or superadmin. The release enters the review queue and is visible under Review → Pending. Once approved, the release is published and available for download.
   • Namespaces with review disabled: The release is published automatically — no draft status, no approval required.

Tip

You can also upload plugins programmatically via the REST API. See the API Reference for details on the upload endpoint.

Verify Upload

Verify via UI

After uploading, navigate to Catalog in the Web UI. Your plugin should appear in the list with its version, tags, and status badge (Published or Pending Review).

Click on the plugin to see the detail page with version history, metadata, and download options.

Verify via API

curl http://localhost:8080/api/v1/namespaces/default/plugins

Your plugin should appear in the JSON response with its plugin ID, version, and status.

What's next

For a fully runnable end-to-end demo — host application + plugins + server, with the install / use / uninstall loop in a real CLI or web UI — see the Examples chapter.