feature: add plugin install system

Author: lukepolo

.gitignore

@@ -1,2 +1,6 @@
 node_modules
 dist
+
+# The installer copies *.env.example -> *.env and fills in your site values.
+*.env
+!*.env.example

README.md

@@ -18,10 +18,26 @@ npm run preview   # serve dist/ at :4173 with CORS, for testing in a real panel
 | --- | --- |
 | `src/App.vue` | Your UI. Receives the logged-in `user` and the host `query` as props. |
 | `vite.config.ts` | Exposes `./App` as a Federation remote; declares shared singletons. |
-| `public/5stack-plugin.json` | The manifest the panel auto-detects. |
+| `public/5stack-plugin.json` | The manifest the panel auto-detects, including the `install` block. |
+| `k8s/` | kustomize package — `base/`, plus an `http` and an `https` overlay. |
 | `tailwind.config.js` | Pulls in the `@5stack/ui` preset so you inherit 5stack theming. |
 | `src/main.ts` | Standalone dev entry — **not** used when embedded in the panel. |
 
+## Install it onto a 5stack cluster
+
+From an operator's `5stack-panel` checkout:
+
+```sh
+./plugin.sh 5stackgg/5stack-example-plugin
+```
+
+That's the whole install: it reads the site's own config for the cluster,
+domain, and whether TLS terminates at the cluster, then applies `k8s/`. This
+repo is the minimal working example of the format — frontend only, so its
+manifest declares no database and no node pinning and the installer skips both
+questions. Copy `k8s/` and the `install` block as your starting point, and see
+[docs.5stack.gg/plugins/installing](https://docs.5stack.gg/plugins/installing).
+
 ## Try it against a running panel
 
 ```sh

k8s/base/deployment.yaml

@@ -0,0 +1,26 @@
+# Frontend only — this plugin has no backend. The container is nginx serving the
+# built Module Federation remote; the panel fetches remoteEntry.js from it.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example-plugin
+spec:
+  selector:
+    matchLabels:
+      app: example-plugin
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: example-plugin
+    spec:
+      containers:
+        - name: example-plugin
+          image: ghcr.io/5stackgg/5stack-example-plugin:latest
+          # :latest is republished on every push to main, so the tag alone
+          # doesn't change — always re-pull it on restart.
+          imagePullPolicy: Always
+          ports:
+            - containerPort: 80
+              name: http

k8s/base/example-plugin.env.example

@@ -0,0 +1,8 @@
+# The host this plugin is served from. It must be a subdomain of the panel if
+# you ever add a backend — the 5stack session cookie is SameSite=Lax and never
+# reaches an unrelated domain.
+#
+# The panel's ./plugin.sh copies this file to example-plugin.env and fills the
+# value in from your site's WEB_DOMAIN; you only need to touch it if you're
+# applying the package by hand.
+EXAMPLE_PLUGIN_DOMAIN=hello.example.com

k8s/base/ingress.yaml

@@ -0,0 +1,29 @@
+# One ingress, no auth annotations: everything this plugin serves is public
+# static JS. There is no API to gate — the panel supplies the logged-in user to
+# the remote as a prop. A plugin with a backend needs more than this; see the
+# inventory plugin's ingresses, which split /api off to a backend Service.
+#
+# CORS and the no-store header on remoteEntry.js are set by the container's
+# nginx.conf, not here.
+#
+# No `tls:` on purpose — the base IS the plain-HTTP install, for sites whose
+# certificate is terminated in front of the cluster. ../overlays/https adds the
+# tls blocks by patch.
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: example-plugin
+  namespace: 5stack
+spec:
+  ingressClassName: nginx
+  rules:
+    - host: ${EXAMPLE_PLUGIN_DOMAIN}
+      http:
+        paths:
+          - backend:
+              service:
+                name: example-plugin
+                port:
+                  number: 80
+            path: /
+            pathType: Prefix

k8s/base/kustomization.yaml

@@ -0,0 +1,32 @@
+# The whole plugin, HTTP-only. Both overlays build from this.
+#
+# The host is written once, into example-plugin.env, and the replacement below
+# pushes it wherever it's needed — here just the ingress rule; the https overlay
+# adds the tls host and the certificate's SAN from the same value. The panel's
+# ./plugin.sh fills that file in for you from your site's WEB_DOMAIN.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+namespace: 5stack
+
+resources:
+  - deployment.yaml
+  - service.yaml
+  - ingress.yaml
+
+configMapGenerator:
+  - name: example-plugin-config
+    envs:
+      - example-plugin.env
+
+replacements:
+  - source:
+      kind: ConfigMap
+      name: example-plugin-config
+      fieldPath: data.EXAMPLE_PLUGIN_DOMAIN
+    targets:
+      - select:
+          kind: Ingress
+          name: example-plugin
+        fieldPaths:
+          - spec.rules.0.host

k8s/base/service.yaml

@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: example-plugin
+spec:
+  ports:
+    - port: 80
+      targetPort: 80
+  selector:
+    app: example-plugin

k8s/kustomization.yaml

@@ -0,0 +1,11 @@
+# Compatibility shim for the panel's ./custom.sh, which builds a directory root
+# and so needs a kustomization here. `./plugin.sh <repo>` doesn't use this file
+# — it builds the overlay it picked for your site directly.
+#
+# Defaults to the plain-HTTP install; point it at overlays/https if your panel
+# terminates TLS at the cluster.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - overlays/http

k8s/overlays/http/kustomization.yaml

@@ -0,0 +1,15 @@
+# Plain-HTTP install — no certificate.
+#
+# For sites where TLS is already terminated in front of the cluster: a
+# Cloudflare proxy or tunnel, or any other reverse proxy. That is the panel's
+# REVERSE_PROXY=true, and ./plugin.sh picks this overlay when it reads that out
+# of your .5stack-env.config.
+#
+# Nothing to add — the base is already HTTP-only. It exists so the two installs
+# are symmetric: one directory each, and the installer just points kustomize at
+# whichever one your site needs.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base

k8s/overlays/https/certificate.yaml

@@ -0,0 +1,27 @@
+# The plugin's own certificate.
+#
+# Not an entry added to the panel's shared 5stack-ssl cert: the panel rebuilds
+# that one from its own overlay on every ./update.sh, so anything a plugin added
+# there would be silently dropped on the next panel update.
+#
+# The Issuer is the namespaced Issuer the panel install creates when the site
+# terminates TLS itself. If yours is named something else, change issuerRef —
+# nothing else in this overlay depends on the name.
+#
+# ${EXAMPLE_PLUGIN_DOMAIN} is substituted by the replacement in
+# kustomization.yaml, from the same file the ingress host comes from.
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: example-plugin-ssl
+  namespace: 5stack
+spec:
+  secretName: example-plugin-ssl
+  # Matches the panel's cert cadence: 90d lifetime, renewed with 10d to spare.
+  duration: 2160h
+  renewBefore: 240h
+  dnsNames:
+    - ${EXAMPLE_PLUGIN_DOMAIN}
+  issuerRef:
+    name: 5stack-issuer
+    kind: Issuer