docs(helm): Add recommended post-installation configuration guide (#556)

roboav8r · kevin-dimichel · web-flow · commit 43408d61c030 · 2026-06-30T16:07:18.000-07:00
* docs(helm): Add recommended post-installation configuration guide

Signed-off-by: John Duncan &lt;30937261+roboav8r@users.noreply.github.com&gt;
Co-authored-by: Kevin DiMichel &lt;56850465+kevin-dimichel@users.noreply.github.com&gt;
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -77,6 +77,7 @@ repos:
           - '-'
           - -i
           - docker/README.md
+          - helm/docs/post-install-recommended-configuration.md
           - helm/fiftyone-teams-app/README.md.gotmpl
           - helm/README.md
           - CONTRIBUTING.md
diff --git a/helm/README.md b/helm/README.md
@@ -25,6 +25,7 @@
       - [Set up http to https Forwarding](#set-up-http-to-https-forwarding)
       - [Install FiftyOne Enterprise App](#install-fiftyone-enterprise-app)
       - [Installation Complete](#installation-complete)
+  - [Recommended Next Steps](#recommended-next-steps)
 
 <!-- tocstop -->
 
@@ -279,3 +280,19 @@ and add your storage credentials to access sample data.
 Congratulations! You should now be able to access your
 FiftyOne Enterprise installation at the DNS address you created
 [earlier](#obtain-a-global-static-ip-address-and-configure-a-dns-entry).
+
+## Recommended Next Steps
+
+The base `helm install` above starts FiftyOne Enterprise with
+**built-in only plugins** and **no delegated operator workers**.
+While sufficient to get started, we recommend enabling
+the following features for a production-ready deployment:
+
+| Step | What it enables |
+| --- | --- |
+| **Dedicated Plugins** | Install and run custom plugins in an isolated `teams-plugins` pod, keeping plugin workloads separate from the main app |
+| **Delegated Operators** | Schedule compute-heavy tasks — embeddings, model evaluation, dataset import, annotation — from the UI and run them on dedicated background workers |
+| **On-Demand Orchestrator** | *(Optional)* Spin up Kubernetes pods on demand per job instead of maintaining always-on workers; more cost-efficient for infrequent or GPU-heavy workloads |
+
+For step-by-step configuration instructions, see
+[Recommended Post-Installation Configuration](./docs/post-install-recommended-configuration.md).
diff --git a/helm/docs/post-install-recommended-configuration.md b/helm/docs/post-install-recommended-configuration.md
@@ -0,0 +1,302 @@
+# Recommended Post-Installation Configuration
+
+<!-- toc -->
+
+- [Prerequisites: Shared Storage](#prerequisites-shared-storage)
+- [Dedicated Plugins Mode](#dedicated-plugins-mode)
+- [Delegated Operators](#delegated-operators)
+  - [On-Demand Delegated Operators](#on-demand-delegated-operators)
+- [GPU Workloads (Optional)](#gpu-workloads-optional)
+  - [Multiple Orchestrators](#multiple-orchestrators)
+- [Advanced: Custom Job Priorities](#advanced-custom-job-priorities)
+- [Verifying Your Setup](#verifying-your-setup)
+- [Getting Started with Plugins](#getting-started-with-plugins)
+
+<!-- tocstop -->
+
+After completing the base Helm installation, we recommend enabling the
+following features for a production-ready FiftyOne Enterprise deployment:
+
+1. [Prerequisites](#prerequisites-shared-storage)
+1. [Dedicated Plugins Mode](#dedicated-plugins-mode)
+1. [Delegated Operators](#delegated-operators)
+1. [GPU Workloads (Optional)](#gpu-workloads-optional)
+
+The default installation uses **built-in plugins** and
+has **no delegated operator workers**.
+While sufficient to get started, it limits the ability to install custom
+plugins and run long-running or compute-heavy tasks in the background.
+
+---
+
+## Prerequisites: Shared Storage
+
+Dedicated plugins and delegated operators share a common plugin directory
+backed by a Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC).
+
+If you do not already have shared storage configured, refer to
+[Adding Shared Storage for FiftyOne Enterprise Plugins](./plugins-storage.md)
+for steps on creating a PV and PVC.
+
+The examples below assume:
+
+- PVC name: `plugins-pvc`
+- Plugin directory: `/opt/plugins`
+
+---
+
+## Dedicated Plugins Mode
+
+By default, plugins run inside the `fiftyone-app` pod (built-in only mode).
+We recommend enabling **dedicated plugins mode**, which runs plugins in their
+own dedicated `teams-plugins` pod. This provides:
+
+- **Custom plugin support** — install plugins from the
+  [FiftyOne Plugin Library](https://github.com/voxel51/fiftyone-plugins) or
+  build your own
+- **Resource isolation** — plugin workloads do not affect `fiftyone-app`
+  stability or performance
+- **Custom dependency support** — plugins with heavy ML dependencies (e.g.
+  `transformers`) are isolated from the main app
+
+There are three plugin modes available:
+
+| Mode | Description |
+| --- | --- |
+| Built-in Only (default) | Only built-in plugins shipped with FiftyOne Enterprise |
+| Shared | Custom plugins run inside `fiftyone-app` — may starve the app |
+| **Dedicated (recommended)** | Custom plugins run in a dedicated `teams-plugins` pod |
+
+To enable dedicated plugins, add the following to your `values.yaml`:
+
+```yaml
+# Dedicated plugins pod
+pluginsSettings:
+  enabled: true
+  env:
+    FIFTYONE_PLUGINS_DIR: /opt/plugins
+
+# teams-api also requires access to the plugins directory
+apiSettings:
+  env:
+    FIFTYONE_PLUGINS_DIR: /opt/plugins
+```
+
+Then apply the changes:
+
+```bash
+helm upgrade fiftyone-teams-app voxel51/fiftyone-teams-app \
+  --values values.yaml \
+  --namespace <your-namespace>
+```
+
+Verify the `teams-plugins` pod is running:
+
+```bash
+kubectl get pods --namespace <your-namespace> | grep teams-plugins
+```
+
+For more details, see
+[Configuring Plugins](./configuring-plugins.md).
+
+---
+
+## Delegated Operators
+
+Delegated operators allow long-running or compute-heavy tasks (such as
+computing embeddings, running model evaluations, importing datasets, or
+annotation workflows) to be scheduled from the FiftyOne UI and executed in
+the background on dedicated compute workers.
+
+To enable delegated operators with dedicated plugins, add the following to
+your `values.yaml`:
+
+```yaml
+delegatedOperatorDeployments:
+  deployments:
+    teamsDo:
+      replicaCount: 3  # adjust based on your concurrency needs
+      env:
+        FIFTYONE_PLUGINS_DIR: /opt/plugins
+      volumes:
+        - name: plugins-vol
+          persistentVolumeClaim:
+            claimName: plugins-pvc
+            readOnly: true
+      volumeMounts:
+        - name: plugins-vol
+          mountPath: /opt/plugins
+```
+
+Then apply the changes:
+
+```bash
+helm upgrade fiftyone-teams-app voxel51/fiftyone-teams-app \
+  --values values.yaml \
+  --namespace <your-namespace>
+```
+
+Verify the `teams-do` pod is running:
+
+```bash
+kubectl get pods --namespace <your-namespace> | grep teams-do
+```
+
+For full configuration options, see
+[Configuring Delegated Operators](./configuring-delegated-operators.md).
+
+### On-Demand Delegated Operators
+
+As an alternative to always-on workers, FiftyOne Enterprise v2.11.0+ supports
+**on-demand delegated operators** that spin up compute pods only when a job is
+scheduled, and tear them down when complete.
+This is more cost-efficient for infrequent or GPU-intensive workloads.
+
+See
+[Configuring On-Demand Orchestrator](../../docs/configuring-on-demand-orchestrator.md)
+for setup instructions.
+
+---
+
+## GPU Workloads (Optional)
+
+If your team runs GPU-accelerated tasks (e.g. computing embeddings with
+`@voxel51/brain`, model evaluation, or custom ML operators), you can schedule
+`teams-do` pods on GPU-enabled nodes using `nodeSelector` and `tolerations`.
+
+Add the following to your `delegatedOperatorDeployments.deployments.teamsDo`
+config in `values.yaml`:
+
+```yaml
+delegatedOperatorDeployments:
+  deployments:
+    teamsDo:
+      nodeSelector:
+        <your-gpu-node-label-key>: <your-gpu-node-label-value>
+        # e.g. node-type: gpu
+      tolerations:
+        - key: "nvidia.com/gpu"
+          operator: "Exists"
+          effect: "NoSchedule"
+      resources:
+        limits:
+          nvidia.com/gpu: 1
+        requests:
+          nvidia.com/gpu: 1
+```
+
+For full details, see
+[Configuring GPU Workloads](./configuring-gpu-workloads.md).
+
+### Multiple Orchestrators
+
+For deployments with mixed workloads, you may
+register multiple delegated operator orchestrators.
+For example, one targeting GPU nodes and one targeting CPU nodes.
+You may run specific operators to the appropriate
+orchestrator from the FiftyOne UI.
+
+```yaml
+delegatedOperatorDeployments:
+  deployments:
+    teamsDoGpu:
+      replicaCount: 1
+      env:
+        FIFTYONE_PLUGINS_DIR: /opt/plugins
+      nodeSelector:
+        node-type: gpu
+      tolerations:
+        - key: "nvidia.com/gpu"
+          operator: "Exists"
+          effect: "NoSchedule"
+      resources:
+        limits:
+          nvidia.com/gpu: 1
+      volumes:
+        - name: plugins-vol
+          persistentVolumeClaim:
+            claimName: plugins-pvc
+            readOnly: true
+      volumeMounts:
+        - name: plugins-vol
+          mountPath: /opt/plugins
+
+    teamsDoCpu:
+      replicaCount: 2
+      env:
+        FIFTYONE_PLUGINS_DIR: /opt/plugins
+      volumes:
+        - name: plugins-vol
+          persistentVolumeClaim:
+            claimName: plugins-pvc
+            readOnly: true
+      volumeMounts:
+        - name: plugins-vol
+          mountPath: /opt/plugins
+```
+
+---
+
+## Advanced: Custom Job Priorities
+
+> **Note:** The Helm chart's `delegatedOperatorJobTemplates.jobs` does not
+> currently support `priorityClassName` natively.
+> To use Kubernetes
+> [PriorityClasses](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/)
+> with delegated operator jobs (for example, to prevent DO workloads from
+> contending with user-facing pods), define custom Jinja2 job templates via a
+> ConfigMap and register them using the
+> [FiftyOne Management SDK](https://docs.voxel51.com/enterprise/management_sdk.html).
+
+See
+[Configuring On-Demand Orchestrator](../../docs/configuring-on-demand-orchestrator.md)
+for details on custom job templates.
+
+---
+
+## Verifying Your Setup
+
+After applying all changes, verify that all expected pods are running:
+
+```bash
+kubectl get pods --namespace <your-namespace>
+```
+
+You should see:
+
+- `teams-plugins-*` — dedicated plugins pod
+- `teams-do-*` (one or more) — delegated operator worker pod(s)
+
+You can also verify delegated operator registration from the FiftyOne Python
+SDK:
+
+```python
+import fiftyone.operators.orchestrator as foo
+
+orc_svc = foo.OrchestratorService()
+for orc in orc_svc.list():
+    print("{} \"{}\" {}".format(orc.instance_id, orc.description, orc.id))
+```
+
+---
+
+## Getting Started with Plugins
+
+Once dedicated plugins are enabled, you can install community plugins from the
+[FiftyOne Plugin Library](https://github.com/voxel51/fiftyone-plugins)
+or the
+[FiftyOne Docs](https://docs.voxel51.com/plugins/index.html).
+
+We recommend starting with these plugins:
+
+- [`@voxel51/brain`](https://github.com/voxel51/fiftyone-plugins/tree/main/plugins/brain)
+  — compute embeddings and similarity indexes
+- [`@voxel51/annotation`](https://github.com/voxel51/fiftyone-plugins/tree/main/plugins/annotation)
+  — annotation workflows
+- [`@voxel51/evaluation`](https://github.com/voxel51/fiftyone-plugins/tree/main/plugins/evaluation)
+  — model evaluation panels
+- [`@voxel51/zoo`](https://github.com/voxel51/fiftyone-plugins/tree/main/plugins/zoo)
+  — access the FiftyOne Model Zoo
+
+To use plugins with custom dependencies (e.g. `transformers`), build and use
+[Custom Plugin Images](https://github.com/voxel51/fiftyone-teams-app-deploy/blob/main/docs/custom-plugins.md).
diff --git a/helm/fiftyone-teams-app/README.md b/helm/fiftyone-teams-app/README.md
@@ -142,6 +142,7 @@ for steps on how to add your license file.
 - [Estimated Completion Time](#estimated-completion-time)
 - [Sizing](#sizing)
 - [Usage](#usage)
+- [Recommended Next Steps](#recommended-next-steps)
 - [Upgrades](#upgrades)
 - [Advanced Configuration](#advanced-configuration)
   - [Backup And Recovery](#backup-and-recovery)
@@ -340,6 +341,16 @@ helm install fiftyone-teams-app voxel51/fiftyone-teams-app \
 A minimal example `values.yaml` may be found
 [in the repository](https://github.com/voxel51/fiftyone-teams-app-deploy/blob/main/helm/values.yaml).
 
+## Recommended Next Steps
+
+The base installation enables FiftyOne Enterprise with
+**built-in only plugins** and **no delegated operator workers**.
+For a production-ready deployment, we recommend enabling **dedicated plugins**
+and **delegated operators** after completing the install above.
+
+See [Recommended Post-Installation Configuration](../docs/post-install-recommended-configuration.md)
+for step-by-step instructions.
+
 ## Upgrades
 
 When performing an upgrade, please review
diff --git a/helm/fiftyone-teams-app/README.md.gotmpl b/helm/fiftyone-teams-app/README.md.gotmpl
@@ -142,6 +142,7 @@ for steps on how to add your license file.
 - [Estimated Completion Time](#estimated-completion-time)
 - [Sizing](#sizing)
 - [Usage](#usage)
+- [Recommended Next Steps](#recommended-next-steps)
 - [Upgrades](#upgrades)
 - [Advanced Configuration](#advanced-configuration)
   - [Backup And Recovery](#backup-and-recovery)
@@ -340,6 +341,16 @@ helm install fiftyone-teams-app voxel51/fiftyone-teams-app \
 A minimal example `values.yaml` may be found
 [in the repository](https://github.com/voxel51/fiftyone-teams-app-deploy/blob/main/helm/values.yaml).
 
+## Recommended Next Steps
+
+The base installation enables FiftyOne Enterprise with
+**built-in only plugins** and **no delegated operator workers**.
+For a production-ready deployment, we recommend enabling **dedicated plugins**
+and **delegated operators** after completing the install above.
+
+See [Recommended Post-Installation Configuration](../docs/post-install-recommended-configuration.md)
+for step-by-step instructions.
+
 ## Upgrades
 
 When performing an upgrade, please review
diff --git a/helm/values.yaml b/helm/values.yaml
@@ -83,6 +83,10 @@ casSettings:
     # Set the name of the Mongo database for CAS if not using the default `cas`
     # CAS_DATABASE_NAME: your-cas-name
 
+# For a production-ready deployment, we recommend enabling dedicated plugins
+# and delegated operators after your initial install. See:
+# https://github.com/voxel51/fiftyone-teams-app-deploy/blob/main/helm/docs/post-install-recommended-configuration.md
+
 # delegatedOperatorDeployments:
 #   deployments:
 #     teamsDoCpuDefault:
