diff --git a/docs.json b/docs.json index 1a6784c5..39453dfb 100644 --- a/docs.json +++ b/docs.json @@ -446,7 +446,8 @@ "enterprise/enterprise-vs-oss", "enterprise/quick-start", "enterprise/analytics", - "enterprise/external-postgres" + "enterprise/external-postgres", + "enterprise/plugin-marketplace" ] }, { diff --git a/enterprise/images/Experimental-PluginMarketplace.png b/enterprise/images/Experimental-PluginMarketplace.png new file mode 100644 index 00000000..5e8a4e97 Binary files /dev/null and b/enterprise/images/Experimental-PluginMarketplace.png differ diff --git a/enterprise/images/PluginMarketplaceClip.gif b/enterprise/images/PluginMarketplaceClip.gif new file mode 100644 index 00000000..2183e43e Binary files /dev/null and b/enterprise/images/PluginMarketplaceClip.gif differ diff --git a/enterprise/plugin-marketplace.mdx b/enterprise/plugin-marketplace.mdx new file mode 100644 index 00000000..0b52d967 --- /dev/null +++ b/enterprise/plugin-marketplace.mdx @@ -0,0 +1,210 @@ +--- +title: Plugin Marketplace +description: Enable and configure the Plugin Marketplace to browse and install community-built OpenHands plugins. +icon: store +--- + +
+
+The Plugin Marketplace is an opt-in feature that adds a browseable catalog of community-built +OpenHands plugins to your Enterprise deployment. Once enabled, users can discover and review +plugins directly at `/plugins` on your application hostname. + + + The Plugin Marketplace is an experimental feature. Enable it only after your + OpenHands Enterprise deployment is fully operational. + +
+
+ Plugin Marketplace demo +
+
+ +## Prerequisites + +- A running OpenHands Enterprise deployment. See [Quick Start](/enterprise/quick-start) if + you haven't already deployed. +- The bundled or [external PostgreSQL](/enterprise/external-postgres) database must be reachable. + The marketplace creates a separate `plugindir` database to store plugin metadata. +- A Marketplace Source URI pointing to a plugin catalog (see [Marketplace Source URI](#marketplace-source-uri)). + +## Enable the Plugin Marketplace + + + + The Plugin Marketplace is configured through the Replicated Admin Console. + + ### 1. Open the Admin Console + + Navigate to `https://:30000` and log in. + + ### 2. Open the configuration page + + Click **Config** in the top navigation bar to open the application configuration page. + + ### 3. Enable the Plugin Directory + + Scroll to the **Experimental** section near the bottom of the configuration page. + + Check the **Enable Plugin Directory** box. + + ![Enable Plugin Directory](/enterprise/images/Experimental-PluginMarketplace.png) + + ### 4. Set the Marketplace Source + + Once **Enable Plugin Directory** is checked, a **Marketplace Source** field appears. + + Enter the URI of the plugin catalog you want to load. For example: + + ```text + github://AcmeCo/plugin-directory + ``` + + To pin to a specific release of the catalog, append a `@ref` tag: + + ```text + github://AcmeCo/plugin-directory@v1.0.0 + ``` + + See [Marketplace Source URI](#marketplace-source-uri) for a full description of supported formats. + + ### 5. Save and deploy + + Scroll to the bottom of the configuration page and click **Save config**, then click **Deploy** + to apply the changes. + + The deployment status will show **Unavailable** while the Plugin Directory pods start, then + transition to **Ready** once all components are healthy. + + + + If you deployed OpenHands Enterprise into your own Kubernetes cluster using Helm, enable the + Plugin Marketplace by adding the following values to your `values.yaml` override file. + + ### Required values + + ```yaml + plugin-directory: + enabled: true + + # Full URL where the plugin catalog is served + appUrl: "https://app./plugins" + + # Base URL used in in-page curl examples + curlApiUrl: "https://app." + + appEnv: + # URI of the plugin catalog to load (required) + MARKETPLACE_SOURCE: "github://AcmeCo/plugin-directory" + + database: + host: "" + name: "plugindir" + # Name of the Kubernetes Secret that contains the PostgreSQL password + secretName: "postgres-password" + secretKey: "password" + + auth: + # Secret created by the openhands-secrets chart + existingSecret: plugin-directory-secrets + + oidc: + # Keycloak issuer URL — must match your Keycloak realm + issuerUrl: "https://auth.app." + realmSecretName: "keycloak-realm" + ``` + + ### Required secrets + + The Plugin Directory needs two shared secrets for inter-service authentication and session + management. Add these to your `openhands-secrets` chart values: + + ```yaml + plugin_directory_identity_shared_secret: "" + plugin_directory_session_secret: "" + ``` + + Generate each value with: + + ```bash + openssl rand -hex 16 + ``` + + ### Apply the changes + + ```bash + helm upgrade openhands oci://ghcr.io/openhands/helm-charts/openhands \ + --namespace openhands \ + --values values.yaml + ``` + + ### Database migration + + On first deployment, init containers automatically create the `plugindir` database and run + Alembic migrations. No manual database setup is required. + + + If you use an external PostgreSQL instance with `databaseMigrations.createDatabases: false`, + create the `plugindir` database manually before deploying. + + + + +## Marketplace Source URI + +The `MARKETPLACE_SOURCE` value (or **Marketplace Source** field in the Admin Console) tells the +Plugin Directory server where to load its plugin catalog from. + +| Format | Example | Notes | +|--------|---------|-------| +| `github://owner/repo` | `github://AcmeCo/plugin-directory` | Loads from the default branch of the repository | +| `github://owner/repo@ref` | `github://AcmeCo/plugin-directory@v1.2.0` | Loads from a specific branch, tag, or commit SHA | +| `https://example.com/catalog.json` | `https://cdn.example.com/plugins/catalog.json` | Loads a catalog JSON file over HTTPS | + + +To host a private or curated catalog, point the URI to a GitHub repository or an HTTPS URL that +serves a compatible catalog JSON file. + +## Accessing the Marketplace + +Once the deployment is complete and shows **Ready**, the Plugin Marketplace is available at: + +```text +https://app./plugins +``` + +Users authenticate through the same Keycloak SSO used for the rest of OpenHands Enterprise. +The Plugin Directory API is also available at: + +```text +https://app./api/plugins +``` + +## Disabling the Plugin Marketplace + + + + Open the Admin Console, navigate to **Config**, uncheck **Enable Plugin Directory** in the + **Experimental** section, click **Save config**, then **Deploy**. + + + Set `plugin-directory.enabled: false` in your `values.yaml` and run `helm upgrade`. + + + +## Next Steps + + + + Install or review the full OpenHands Enterprise deployment guide. + + + Configure an external PostgreSQL database for OpenHands Enterprise. + + + Deploy OpenHands Enterprise into your own Kubernetes cluster using Helm. + + + Learn about all OpenHands Enterprise features and deployment options. + +