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: Set Up MongoDB Database
🔐 Step 2: Prepare License File
📁 Step 3: Choose Authentication Mode
⚙️ Step 4: Configure Environment
- 1. Copy the template .env file
- 2. Fill out required values in .env
- 3. Create a compose.override.yaml to override configuration
- 📦 Official Docker Images
🚀 Step 5: Initial Deployment
- 1. Database admin mode
- 2. Launch the application
🌐 Step 6: Configure SSL & Reverse Proxy (Nginx / Load Balancer)
- 🧭 Routing Overview (Path-Based Proxy)
- 📂 Nginx Configuration
- 📝 Notes
📄 Step 7: Configure Delegated Operation Logs
Step 8: Identity Provider (IdP) and Authentication (CAS)
- ℹ️ IdP configuration
- 🛠️ Optional: CAS Customization Instructions
Step 9: Initial CAS Setup
- Add First Admin User
- Enable Auto Join
Step 10: Test End User Login
Advanced DO Settings
- 🖥️ GPU-Enabled Workloads
- 🧱 Custom Plugin Images
- 🔛 On-Demand Delegated Operator Executors
Upgrades
Known Issues
Advanced Configuration
- Backup And Recovery
- Secrets And Sensitive Data
- Telemetry
- Snapshot Archival
- Static Banner Configuration
- Storage Credentials and FIFTYONE_ENCRYPTION_KEY
- Terms of Service, Privacy, and Imprint URLs
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: Set Up MongoDB Database

Before deploying FiftyOne Enterprise, you must have a running MongoDB database. FiftyOne Enterprise supports:

MongoDB Atlas (managed cloud)
MongoDB Community Edition (self-hosted, open source)
MongoDB Enterprise (self-hosted, commercial)

Ensure your MongoDB version meets FiftyOne's version constraints. MongoDB 8.0+ is recommended.

Once your database is running, record your MongoDB connection URI. You will need it in Step 4 when configuring your .env file. The URI follows this format:

FIFTYONE_DATABASE_URI="mongodb://username:password@mongodb-example.fiftyone.ai:27017/?authSource=admin"

🔐 Step 2: 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 3: Choose Authentication Mode

FiftyOne Enterprise supports two authentication modes. Choose the one that matches your deployment:

Mode	Use when
`internal-auth`	Deployment is Air-gapped or Identity Provider is OpenID Connect (OIDC)
`legacy-auth`	Identity Provider is SAML

Navigate into the appropriate directory:

cd internal-auth  # or legacy-auth

⚙️ Step 4: 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

Create an overrides file (compose.override.yaml) and add overrides there. Avoid changing the yaml files in this directory and instead use overrides.

For example, adding a variable to the fiftyone-app service would look like:

services:
  fiftyone-app:
    environment:
      EXAMPLE_VARIABLE: example-value

📦 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.20.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 5: Initial Deployment

1. Database admin mode

A fresh install does not require database admin mode (as of v2.9+) — a new database automatically initializes to the connecting client's version, so no migration is needed. Keep FIFTYONE_DATABASE_ADMIN: false (the default) in compose.override.yaml:

services:
  fiftyone-app:
    environment:
      FIFTYONE_DATABASE_ADMIN: false

2. Launch the application

FiftyOne Enterprise is deployed with Dedicated Plugins and Delegated Operators enabled by default. Dedicated Plugins run in an isolated teams-plugins container. Delegated Operators offload plugin execution to worker containers, enabling scalable and reliable long-running operations.

docker compose \
  -f compose.dedicated-plugins.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

For a full health assessment, see Basic Health Assessment.

🌐 Step 6: 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

All services are routed based on URL path using a single hostname via path based routing. See a full example configuration in example-nginx-path-routing.conf

📝 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 7: Configure Delegated Operation Logs

Add the log path for delegated operation runs to your compose.override.yaml:

services:
  teams-do:
    environment:
      FIFTYONE_DELEGATED_OPERATION_LOG_PATH: "gs://your-bucket/logs"

Logs are 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.

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.

Step 9: Initial CAS Setup

Navigate to the CAS Super Admin UI at https://<ENVIRONMENT>.fiftyone.ai/cas/configurations.
In the API Key field (upper right corner), enter the value of FIFTYONE_AUTH_SECRET (from your .env file)

Add First Admin User

Navigate to the Admins tab at https://<ENVIRONMENT>.fiftyone.ai/cas/admins.
Select Add admin.
Provide Name and Email.
Select Add.

Enable Auto Join

Navigate to https://<ENVIRONMENT>.fiftyone.ai/cas/providers.
Select + Edit.
Select Allow auto join.
Select Save.

Step 10: Test End User Login

Verify the deployment's IdP setup by logging in as a regular user.

In a browser, open https://<ENVIRONMENT>.fiftyone.ai.
Log in with the user credentials of the admin you created in the CAS Super Admin UI.
Confirm you are redirected to the FiftyOne Enterprise home page.

Advanced DO Settings

🖥️ GPU-Enabled Workloads

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

To set up 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. Use voxel51/fiftyone-teams-cv-full as the base image (that includes a full CV/ML environment), and extend with:

Custom Python packages
Internal SDKs or models

Once built, reference your custom image in compose.override.yaml:

services:
  teams-do:
    image: fiftyone-cv-full-custom:v2.19.0

🔛 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 configuring delegated operators documentation.

Upgrades

The recommended upgrade path is:

Pull the latest compose files from this repo:
```
git pull origin main
```
This automatically populates the latest service versions.
Confirm FIFTYONE_DATABASE_ADMIN is set to false in your compose.override.yaml:
```
services:
  fiftyone-app:
    environment:
      FIFTYONE_DATABASE_ADMIN: false
```
This prevents automatic database migrations from running on startup and breaking active SDK sessions.
When using Custom Plugin Images, rebuild them using the updated base image version. Update their tags in compose.override.yaml to match the new release.

Bring the compose stack down:

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

Bring the new stack up:

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

For full upgrade guidance, refer to Upgrading.

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