FiftyOne Enterprise: Docker Deployment Guide

FiftyOne Enterprise is the enterprise version of the open source FiftyOne project.

The FiftyOne Enterprise Docker Compose files are the recommended way to install and configure FiftyOne Enterprise on Docker.

This guide walks you through the steps for installing FiftyOne Enterprise using Docker Compose. It also includes advanced configuration, environment variables, and upgrade considerations. This page assumes general knowledge of FiftyOne Enterprise and how to use it. Please contact Voxel51 for more information regarding FiftyOne Enterprise.

📗 Prerequisites Skills and Knowledge
✅ Technical Requirements
🕙 Estimated Completion Time
💾 Sizing
🔐 Step 1: Prepare License File
📁 Step 2: Choose Authentication Mode
- 👉 Choose your mode
⚙️ Step 3: Configure Environment
🚀 Step 4: Initial Deployment
- 1. Enable Database Admin mode
- 2. Launch the application
🌐 Step 5: Configure SSL & Reverse Proxy (Nginx / Load Balancer)
🧩 Step 6: Configuring FiftyOne Enterprise Plugins
⚙️ Step 7: Advanced Delegated Operations Configuration (Optional)
Step 8: Identity Provider (IdP) and Authentication (CAS)
- ℹ️ IdP configuration
- 🛠️ Optional: CAS Customization Instructions
Upgrades
Known Issues
Advanced Configuration
Validating
Health Checks And Monitoring
- Basic Health Assessment
- Troubleshooting Unhealthy Containers
Environment Variables

📗 Prerequisites Skills and Knowledge

The following prerequisites skills & knowledge are required for a successful and properly secured deployment of FiftyOne Enterprise.

A knowledge of:

Docker compose.
MongoDB.
DNS and the ability to generate, modify, and delete DNS records.
TLS/SSL and the ability to generate TLS/SSL certificates.

✅ Technical Requirements

Docker and Docker Compose installed.
License file from Voxel51.
Docker Hub credentials from Voxel51.
A MongoDB Database that meets FiftyOne's version constraints.
A DNS record or records for ingress.
A TLS/SSL certificate or certificates for HTTPS ingress.

🕙 Estimated Completion Time

The estimated time to deploy FiftyOne Enterprise is approximately 2 hours.

💾 Sizing

Voxel51 recommends the following resource sizing:

MongoDB: 4 CPU, 16GB RAM, 256GB Storage
Docker Compose Server: 8 CPU, 32GB RAM, 256GB Storage

Voxel51 also recommends monitoring resource consumption across the applications. Resource usage varies dramatically with operations, use cases, and dataset sizes.

🔐 Step 1: Prepare License File

Required for v2.0+

Set LOCAL_LICENSE_FILE_DIR in your .env
Place the license file there and rename it to license
Ensure the license directory is volume-mounted into the containers (e.g., /opt/data/licenses/)
Set read permissions on the license file: chmod 644 license

# Set this to match the LOCAL_LICENSE_FILE_DIR value in your .env file
LOCAL_LICENSE_FILE_DIR="/path/to/your/licenses"
mkdir -p "${LOCAL_LICENSE_FILE_DIR}"
mv license.key "${LOCAL_LICENSE_FILE_DIR}/license"
chmod 644 "${LOCAL_LICENSE_FILE_DIR}/license"

Tip

When rotating the license, to ensure that the new license values are picked up immediately, you may need to restart the teams-cas and teams-api services.

📁 Step 2: Choose Authentication Mode

FiftyOne Enterprise offers two authentication modes:

legacy-auth → Choose this mode if using Auth0 for user authentication and authorization.
internal-auth → Choose this mode when in an airgapped deployment - aigapped deployments will not require network egress to external services.

👉 Choose your mode

Navigate into the appropriate directory:

cd legacy-auth       # or internal-auth

⚙️ Step 3: Configure Environment

1. Copy the template `.env` file

cp env.template .env

2. Fill out required values in `.env`

At minimum, configure:

BASE_URL / AUTH0_BASE_URL - Your WebApp URL
FIFTYONE_API_URI - Your API URL (can be the same as webApp URL if using path-based routing)
FIFTYONE_DATABASE_URI – Your MongoDB connection URI
FIFTYONE_ENCRYPTION_KEY – Used to encrypt storage credentials

🔑 To generate a key:

from cryptography.fernet import Fernet
print(Fernet.generate_key().decode())

LOCAL_LICENSE_FILE_DIR – Path where the license is mounted
FIFTYONE_AUTH_SECRET – Shared secret for CAS and App auth
Any other variables noted in the .env.template or listed in the Environment Variables section

3. Create a `compose.override.yaml` to override configuration

services:
  fiftyone-app:
    environment:
      FIFTYONE_DATABASE_ADMIN: true # Only for first install

📦 Official Docker Images

Voxel51 publishes the following private FiftyOne Enterprise images to Docker Hub:

voxel51/fiftyone-app
voxel51/fiftyone-app-gpt
voxel51/fiftyone-app-torch ← for text similarity / PyTorch support
voxel51/fiftyone-teams-api
voxel51/fiftyone-teams-app
voxel51/fiftyone-teams-cas
voxel51/fiftyone-teams-cv-full ← full CV/ML environment

🔐 For access, contact your Voxel51 support team to obtain Docker Hub credentials.

You can override the default image used by any service in compose.override.yaml. For example:

services:
  fiftyone-app:
    image: voxel51/fiftyone-app-torch:v2.21.0

Note

Default images and versions for all services are defined in common-services.yaml. To override an image or version, set the value in compose.override.yaml. For example, instead of using the fiftyone-app image, you may instead the fiftyone-app-gpt image. Always include a version tag when overriding images (e.g., :vX.Y.Z). Omitting the tag will result in a not found error.

🚀 Step 4: Initial Deployment

1. Enable Database Admin mode

In compose.override.yaml, make sure:

services:
  fiftyone-app:
    environment:
      FIFTYONE_DATABASE_ADMIN: false

This allows the application to create and migrate the database schema.

2. Launch the application

It is highly recommended to set up your FiftyOne Enterprise Deployment with Delegated Operation. Delegated Operators allow FiftyOne Enterprise to offload plugin execution to worker containers, enabling scalable and reliable long-running operations.

To launch worker containers, include compose.delegated-operators.yaml in your docker compose commands

docker compose \
  -f compose.yaml \
  -f compose.delegated-operators.yaml \
  -f compose.override.yaml \
  up -d

This will start the following containers:

fiftyone-app (embedded API) → default port 5151
fiftyone-teams-app (UI) → default port 3000
fiftyone-teams-api (API) → default port 8000
fiftyone-teams-cas (Auth) → default port 3030
fiftyone-teams-do-n where n is the number of VPUs your in deployment

You can ensure that all your containers are up and healthy through:

docker compose ps

For HTTP-based health checks, run the following curl commands:

curl -Iv http://localhost:3030/cas/api
# Expected: HTTP/1.1 200 OK

curl -Iv http://localhost:8000/health
# Expected: HTTP/1.1 200 OK

curl -Iv http://localhost:3000/api/hello
# Expected: HTTP/1.1 200 OK

🌐 Step 5: Configure SSL & Reverse Proxy (Nginx / Load Balancer)

Next, you will need to place a reverse proxy or SSL endpoint in front of your FiftyOne Enterprise services. This can be a tool like:

Nginx
HAProxy
Cloud Load Balancer (e.g., AWS ALB, GCP Load Balancer)

These proxies will:

Route traffic to the correct services (teams-app, teams-api, teams-cas)
Terminate HTTPS/SSL (if using TLS)
Optionally apply authentication headers, logging, or load balancing

🧭 Routing Overview (Path-Based Proxy)

Path	Proxied To	Description
`/`	`teams-app`	Main web UI
`/cas`	`teams-cas`	Central Authentication Service (CAS)
`/cloud_credentials`	`teams-api`	Cloud credentials API endpoint
`/graphql/v1`	`teams-api`	GraphQL API endpoint
`/rpc`	`teams-api`	RPC API endpoint
`/file`	`teams-api`	File import handling
`/_pymongo`	`teams-api`	MongoDB requests via SDK
`/health`	`teams-api`	Health check endpoint

📂 Nginx Configuration Options

Voxel51 provides example Nginx configs for two routing strategies:

🔹 1. Path-Based Routing

All services are routed based on URL path:

📄 Full configuration here: example-nginx-path-routing.conf

🔹 2. Hostname-Based Routing

teams-app and teams-api are routed using different subdomain or hostname:

fiftyone.your-company.com → App
fiftyone-api.your-company.com → API

📄 Full configuration here:

example-nginx-site.conf (App + CAS)
example-nginx-api.conf (API)

📝 Notes

FiftyOne Enterprise supports routing traffic through proxy servers. Please refer to the proxy configuration documentation for information on how to configure proxies.
To validate your deployments api connection, see Validating Your Deployment

🧩 Step 6: Configuring FiftyOne Enterprise Plugins

FiftyOne Enterprise supports three plugin modes: Builtin, Shared, and Dedicated. Each offers different trade-offs in isolation, flexibility, and resource management.

🔹 1. Builtin Plugins Only (Default)

This is the default configuration. It enables only the plugins shipped with the platform.

✅ No additional configuration needed.

🔹 2. Shared Plugins

Custom plugins are run within the same container as the app (fiftyone-app). Use this if:

You want to quickly prototype plugins
You’re okay with shared resource usage between app and plugins

Enable shared plugin mode

Use compose.plugins.yaml (instead of compose.yaml)
This mounts a shared volume for plugins across services

docker compose \
  -f compose.plugins.yaml \
  -f compose.delegated-operators.yaml \
  -f compose.override.yaml \
  up -d

📁 Plugins will run inside the fiftyone-app container.

🔹 3. RECOMMENDED: Dedicated Plugins

Custom plugins are run in a separate teams-plugins container, isolated from the app and API services.

Use this mode when:

You want full isolation and stability
You are running many or complex plugins
You need to manage plugin memory or compute separately

Enable dedicated plugin mode

Ensure your .env file includes the following:

FIFTYONE_TEAMS_PLUGIN_URL=http://teams-plugins:5151

Use compose.dedicated-plugins.yaml (instead of compose.yaml)

docker compose \
  -f compose.dedicated-plugins.yaml \
  -f compose.delegated-operators.yaml \
  -f compose.override.yaml \
  up -d

Optional: If using a proxy server, ensure the plugin service is excluded from proxying.

🔧 This prevents traffic from being routed incorrectly through your proxy for internal plugin calls.

📌 Notes

All plugin modes require persistent storage (volumes) for plugin files.
For multi-node deployments, ensure that the volume is available on all nodes.
To manage and deploy plugins via the UI, go to: https://<your-domain>/settings/plugins

⚙️ Step 7: Advanced Delegated Operations Configuration (Optional)

📄 Upload Run Logs

You can enable log uploads for delegated operation runs by setting:

FIFTYONE_DELEGATED_OPERATION_LOG_PATH=/mnt/shared/logs

Logs will be stored in the format:

/mnt/shared/logs/do_logs/<YYYY>/<MM>/<DD>/<RUN_ID>.log

This is useful for auditing, debugging, or monitoring delegated operator executions in shared storage or cloud buckets.

🖥️ GPU-Enabled Workloads

FiftyOne services like Delegated Operators can be scheduled on GPU-enabled hardware for more efficient computation.

To setup containers with GPU resources, see the configuring GPU workloads documentation.

🧱 Custom Plugin Images

If your delegated operators or plugins require custom dependencies, build and deploy custom plugin images. You can base them on voxel51/fiftyone-app, and include:

Custom Python packages
ML libraries (e.g. PyTorch, OpenCV)
Internal SDKs or models

🔛 On-Demand Delegated Operator Executors

FiftyOne Enterprise v2.11 introduces support for on-demand delegated operator executors for Databricks and Anyscale. Please refer to the configuration documentation.

Step 8: Identity Provider (IdP) and Authentication (CAS)

ℹ️ IdP configuration

You can refer to the following docs to set up your Identity Provider with FiftyOne.

Pluggable authentication docs includes information on configuring CAS.
To set up authentication for internal-auth mode: Refer to the Getting Started with Internal Mode documentation.

FiftyOne Enterprise uses a Central Authentication Service (CAS) introduced in v1.6. This enables centralized login, roles, and user management.

🛠️ Optional: CAS Customization Instructions

Update required CAS variables in .env:
- FIFTYONE_AUTH_SECRET
- CAS_BASE_URL
- CAS_BIND_ADDRESS
- CAS_BIND_PORT
- CAS_DATABASE_NAME (⚠️ Must be unique per deployment)
- CAS_DEBUG
- CAS_DEFAULT_USER_ROLE
Update compose.override.yaml with any needed teams-cas service changes.
Use docker compose from within the legacy-auth/internal-auth directory to bring up services.
Ensure your proxy (e.g., nginx) forwards /cas to the CAS service port.

Upgrades

When upgrading FiftyOne Enterprise, you must explicitly prevent automatic database migrations to avoid breaking active SDK sessions or deployments.

🚫 Disable Automatic Migrations

Before running your upgraded containers, set the following override:

services:
  fiftyone-app:
    environment:
      FIFTYONE_DATABASE_ADMIN: false

This ensures that no automatic migrations will occur when the container starts.

The environment variable FIFTYONE_DATABASE_ADMIN acts as a safeguard to prevent the database from being modified automatically.

🛠️ What Happens If You Migrate with database admin False?

If FIFTYONE_DATABASE_ADMIN=false is set, and a migration attempt is made via CLI:

$ fiftyone migrate --all
Traceback (most recent call last):
...
OSError: Cannot migrate database from v0.22.0 to v0.22.3 when database_admin=False.

or no action will be taken:

$ fiftyone migrate --info
FiftyOne Enterprise version: 0.14.4

FiftyOne compatibility version: 0.22.3
Other compatible versions: >=0.19,<0.23

Database version: 0.21.2

dataset     version
----------  ---------
quickstart  0.22.0
$ fiftyone migrate --all
$ fiftyone migrate --info
FiftyOne Enterprise version: 0.14.4

FiftyOne compatibility version: 0.23.0
Other compatible versions: >=0.19,<0.23

Database version: 0.21.2

dataset     version
----------  ---------
quickstart  0.21.2

📚 Next Steps

After disabling FIFTYONE_DATABASE_ADMIN, refer to:

Upgrading

for complete guidance on upgrading from previous versions

Known Issues

For a list of common issues and their solutions, refer to the 📄 Known Issues documentation.

If you encounter a new issue, please open a ticket on the 📬 GitHub Issues page.

Advanced Configuration

Backup And Recovery

FiftyOne Enterprise data is stored in MongoDB. It is recommended to periodically backup the MongoDB instance according to MongoDB best practices.

If needed, it is recommended to restore the most-recent backup according to MongoDB best practices

Secrets And Sensitive Data

By default, database credentials, cookie secrets, encryption keys, and authentication secrets are stored in environment variables. This is configured by the following settings in .env:

# This should be a MongoDB Connection String for your database
FIFTYONE_DATABASE_URI="mongodb://username:password@mongodb-example.fiftyone.ai:27017/?authSource=admin"
# If you are using a different MongoDB Connection String for your CAS database,
#  set it here
# CAS_MONGODB_URI="mongodb://username:password@mongodb-cas-example.fiftyone.ai:27017/?authSource=admin"

# FIFTYONE_AUTH_SECRET is a random string used to authenticate to the CAS service
# This can be any string you care to use generated by any mechanism you prefer.
# You could use something like:
#  `cat /dev/urandom | LC_CTYPE=C tr -cd '[:graph:]' | head -c 32`
#  to generate this string.
# This is used for inter-service authentication and for the SuperUser to
#  authenticate at the CAS UI to configure the Central Authentication Service.
FIFTYONE_AUTH_SECRET=

# This key is required and is used to encrypt storage credentials in the MongoDB
#   do NOT lose this key!
# generate keys by executing the following in python:
#
# from cryptography.fernet import Fernet
# print(Fernet.generate_key().decode())
#
FIFTYONE_ENCRYPTION_KEY=

FIFTYONE_DEFAULT_APP_PORT=5151

FiftyOne Enterprise supports configuring secrets for the deployment to use.

Please see Storage Credentials and FIFTYONE_ENCRYPTION_KEY and adding secrets for questions regarding storage and encryption.

Telemetry

FiftyOne Enterprise bundles a telemetry sidecar and Redis backend by default in every compose file. The Settings → Metrics page in teams-app exposes live per-service metrics (CPU, memory, FDs, thread counts) and tailed logs.

Please refer to the telemetry configuration documentation for full details.

Snapshot Archival

Since version v1.5, FiftyOne Enterprise supports archiving snapshots to cold storage locations to prevent filling up the MongoDB database. Supported locations are network mounted filesystems and cloud storage folders.

Please refer to the snapshot archival configuration documentation for configuring snapshot archival.

Static Banner Configuration

FiftyOne Enterprise v2.6 introduces the ability to add a static banner to the application.

Banner text is configured with FIFTYONE_APP_BANNER_TEXT.

Banner background color is configured with FIFTYONE_APP_BANNER_COLOR.

Banner text color is configured with: casSettings.env.FIFTYONE_APP_BANNER_TEXT_COLOR and teamsAppSettings.env.FIFTYONE_APP_BANNER_TEXT_COLOR

Examples:

services:
  teams-app-common:
    environment:
      FIFTYONE_APP_BANNER_COLOR: `green | rgb(34,139,34") | '#f1f1f1'`
      FIFTYONE_APP_BANNER_TEXT_COLOR: `green | rgb(34,139,34") | '#f1f1f1'`
      FIFTYONE_APP_BANNER_TEXT: "Internal Deployment"
  teams-cas-common:
    environment:
      FIFTYONE_APP_BANNER_COLOR: `green | rgb(34,139,34") | '#f1f1f1'`
      FIFTYONE_APP_BANNER_TEXT_COLOR: `green | rgb(34,139,34") | '#f1f1f1'`
      FIFTYONE_APP_BANNER_TEXT: "Internal Deployment"

Storage Credentials and `FIFTYONE_ENCRYPTION_KEY`

Containers based on the fiftyone-teams-api and fiftyone-app images must include the FIFTYONE_ENCRYPTION_KEY variable. This key is used to encrypt storage credentials in the MongoDB database.

To generate a value for FIFTYONE_ENCRYPTION_KEY, run this Python code and add the output to your .env file.

from cryptography.fernet import Fernet
print(Fernet.generate_key().decode())

Voxel51 does not have access to this encryption key and cannot reproduce it. Please store this key in a safe place. If the key is lost, you will need to

Schedule an outage window
1. Drop the storage credentials collection
2. Replace the encryption key
3. Add the storage credentials via the UI again.

Users with Admin permissions may use the FiftyOne Enterprise UI to manage storage credentials by navigating to https://<DEPOY_URL>/settings/cloud_storage_credentials.

If added via the UI, storage credentials no longer need to be mounted into containers or provided via environment variables.

FiftyOne Enterprise continues to support the use of environment variables to set storage credentials in the application context and is providing an alternate configuration path.

Terms of Service, Privacy, and Imprint URLs

FiftyOne Enterprise v2.6 introduces the ability to override the Terms of Service, Privacy, and Imprint (optional) links if required in the App.

Configure the URLs by setting the following environment variables in your compose.override.yaml.

Privacy URL is configured with FIFTYONE_APP_PRIVACY_URL.

Imprint/Impressum URL is configured with FIFTYONE_APP_IMPRINT_URL