Version: 3.0

ON-Prem Installation Guide

This chapter covers system requirements and installation procedures for self-hosted Operaide deployments.

System Requirements

Minimum Hardware Requirements

These are the base requirements for a single Operaide instance with minimal usage.

Component	Minimum	Recommended
CPU	1 core	2+ cores
RAM	1.5 GB	4 GB
Storage	10 GB	50 GB+

Additional Resources for Parallel Usage

The base requirements above cover the application and database. Active usage of Operaide Studio and parallel app execution require additional resources on top of the base.

Per Parallel App Execution

Each concurrently running app (Reaktor) adds load to the instance. App execution is predominantly I/O-bound when calling external AI providers, but document processing and local computations require additional CPU.

Resource	Per Parallel App
CPU	~0.5 cores
RAM	~200 MB

Per Operaide Studio Session

Each user with an active Operaide Studio session runs a dedicated backend process. Resource usage grows with the number of open files, active terminals, and installed extensions.

Resource	Per Studio Session
CPU	~0.5 cores
RAM	200–400 MB

info

Studio sessions are started on demand and automatically cleaned up when inactive. Only active sessions consume resources.

Storage Considerations

Storage requirements depend on your usage pattern. The main drivers are:

Component	Typical Usage
Application + Runtime	~3 GB
Database (embedded MongoDB)	Scales with document count — from < 1 GB (pilot) to 100 GB+ (intensive use)
Studio Workspaces	~1–2 GB per user
Uploaded Documents	Depends on your document volume
Logs	2–5 GB

Plan storage based on your expected database size and number of Studio users. A rough formula:

Storage = 3 GB + Database Size + (Number of Users × 2 GB) + Expected Upload Volume + 5 GB Logs + 20% Buffer

Software Requirements

Docker 20.10+ with Docker Compose v2
Network: Outbound HTTPS (443) — see Network Requirements for details

info

Operaide ships with an embedded MongoDB inside the application container. You do not need to install or run MongoDB separately.

Supported Platforms

Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+)
Windows Server 2019+ with WSL2
macOS (development only)

Network Requirements

Operaide requires outbound HTTPS connectivity to external services. All connections are outbound only — no inbound connections to the Operaide server are required beyond user access to the web interface.

Installation Identity

Each Operaide installation has a unique identity consisting of:

Authentication token — a unique token (format: oprd_ followed by 32 hexadecimal characters) configured via the OPERAIDE_AUDITING_TOKEN environment variable
Customer association — one customer can have multiple installations
Organization tracking — organizations within each installation are tracked automatically

This token authenticates your installation for all communication with the Operaide audit service.

Audit Service (Required)

Your installation connects to the Operaide audit service at https://audit.operaide.ai to report usage metrics and enable platform services.

Detail	Value
URL	`https://audit.operaide.ai` (configurable via `OPERAIDE_AUDITING_URL`)
Protocol	Outbound HTTPS (port 443)
Frequency	Every 24 hours
Auth	Bearer token (`OPERAIDE_AUDITING_TOKEN`)

Data transmitted:

Usage metrics — user counts, AI token consumption (per provider and model), reaktor execution statistics
Storage metrics — database sizes, file storage usage
System information — platform version, build date, environment
Mail relay — if you use the built-in mail integration, outbound emails are routed through the audit service

info

The audit service URL defaults to https://audit.operaide.ai. You can override it with the OPERAIDE_AUDITING_URL environment variable if your deployment uses a custom audit endpoint.

AI Provider APIs (Required for Configured Providers)

Operaide connects to cloud AI providers over HTTPS (port 443). You only need to allow outbound connections to the providers you actually configure in the Operaide UI.

Provider	API Endpoint
OpenAI	`api.openai.com`
Anthropic	`api.anthropic.com`
Azure OpenAI	`*.openai.azure.com` (your endpoint)
Amazon Bedrock	Region-specific AWS endpoints
Google Vertex AI	Region-specific GCP endpoints
Google Generative AI	`generativelanguage.googleapis.com`
Mistral	`api.mistral.ai`
Groq	`api.groq.com`
Cohere	`api.cohere.ai`
DeepSeek	`api.deepseek.com`
Cerebras	`api.cerebras.ai`

External Integrations (Optional)

Depending on your reaktor apps, additional outbound HTTPS connections may be needed:

Web scraping services (e.g., Jina AI) — if configured under Connections
ERP systems — if used in reaktor integrations
Custom APIs — any external endpoints called by your reaktor workflows

Proxy Configuration

If your environment routes outbound traffic through a corporate proxy server, Operaide supports this out of the box. Configure proxy settings using standard environment variables:

Variable	Purpose
`HTTP_PROXY`	Proxy server for HTTP requests (e.g., `http://proxy:8080`)
`HTTPS_PROXY`	Proxy server for HTTPS requests (e.g., `http://proxy:8080`)
`NO_PROXY`	Comma-separated list of hosts that bypass the proxy

The NO_PROXY variable supports the following patterns:

Domain wildcards: .example.com (matches all subdomains)
Exact hostnames: localhost, intranet.company.local
Port-specific rules: localhost:7077
IP addresses: 127.0.0.1, 192.168.1.10
Wildcard bypass: * (bypasses proxy for all hosts)

Example Docker Compose configuration:

services:
  app:
    environment:
      HTTP_PROXY: http://proxy.company.com:8080
      HTTPS_PROXY: http://proxy.company.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com,mongo

warning

If you run MongoDB as a separate container (see External MongoDB), always include its service name (e.g. mongo) in your NO_PROXY list to prevent database traffic from being routed through the proxy. With the default embedded MongoDB, localhost and 127.0.0.1 are sufficient.

Operaide automatically applies these settings to all outbound HTTP and HTTPS requests — no additional configuration is needed.

Upstream NPM Registry

Operaide Apps and libraries are NPM packages. Developers publish them with npm publish to your instance's built-in registry at /api/v1/registry. Packages whose name begins with operaide-app- appear in the App Store. Libraries (typically @operaide/<name>) are pulled in as App dependencies.

Why an upstream registry

Your instance's registry holds packages that were published directly to it. When an App declares a dependency that is not present locally, your instance forwards the request to an upstream registry. Examples: a library you keep on another internal registry, an open-source package from registry.npmjs.org, or an App that lives on another Operaide instance.

The default upstream is https://registry.npmjs.org. Override it for a private registry: Verdaccio, GitHub Packages, npm Enterprise, or another Operaide instance.

Configuration

Configure both via environment variables:

Variable	Purpose
`NPM_UPSTREAM_REGISTRY_URL`	Upstream registry root. Default `https://registry.npmjs.org`.
`NPM_UPSTREAM_REGISTRY_AUTH_TOKEN`	Bearer token for read access against the upstream. Empty for a public upstream.

Public upstream (default)

With NPM_UPSTREAM_REGISTRY_AUTH_TOKEN empty, Operaide returns a 302 Found redirect for tarball and metadata requests that miss the local registry. The user's npm client then fetches from the upstream CDN directly. This is the default and the most efficient path for registry.npmjs.org.

Authenticated upstream

With NPM_UPSTREAM_REGISTRY_AUTH_TOKEN set, Operaide proxies the request itself instead of redirecting. Operaide attaches the configured Bearer token; the user's npm client never receives it.

Use this when the upstream is a private registry such as Verdaccio, GitHub Packages, npm Enterprise, or another Operaide instance.

warning

A 302 redirect cannot pass authentication to the upstream. If your upstream rejects unauthenticated reads, App downloads will fail with 403 Forbidden until you set NPM_UPSTREAM_REGISTRY_AUTH_TOKEN.

Network requirements

The Operaide container must reach the upstream registry over HTTPS. Behind a corporate proxy, this is covered by HTTPS_PROXY (see Proxy Configuration).

Common mistakes

Configuring the upstream URL but forgetting the read token when the upstream is private. The platform falls back to a redirect, which the npm client cannot authenticate.
Trailing slash in NPM_UPSTREAM_REGISTRY_URL is harmless. Operaide normalises the value at startup.
Confusing this token with NPM_BUILTIN_REGISTRY_AUTH_TOKEN. The latter authenticates clients to this instance's registry; the upstream token authenticates this instance to the upstream.

On-Premises Installation

Step 1: Prepare Docker Compose

Create a compose.yml file. This uses Operaide's embedded MongoDB — a single container runs both the application and the database.

name: operaide
services:
  operaide:
    image: ghcr.io/objective-partner/op-no-gravity-operaide:${TAG}
    ports:
      # IMPORTANT: the host and container port MUST be the same.
      - "${PORT:-7077}:${PORT:-7077}"
    restart: always
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 4096M
    volumes:
      - app:/app/bundle/programs/server/assets/app/
      - uploads:/srv/uploads
      - data:/data
      - mongodb:/mongodb
    environment:
      ROOT_URL: ${ROOT_URL}
      PORT: ${PORT:-7077}
      NO_REGISTRATION: ${NO_REGISTRATION:-false}
      MAIL_URL: ${MAIL_URL}
      ENVCFG_MAIL_SENDER: ${MAIL_SENDER}
      METEOR_APP_ROOT: /srv
      # Audit Service
      OPERAIDE_AUDITING_TOKEN: ${OPERAIDE_AUDITING_TOKEN}
      OPERAIDE_AUDITING_URL: https://audit.operaide.ai
      OPERAIDE_AUDITING_ENABLED: "true"
      # MONGO_URL is not set — Operaide uses its embedded MongoDB.
      # To use an external MongoDB instead, see "External MongoDB" below.
      # Proxy (optional — uncomment if behind a corporate proxy)
      # HTTP_PROXY: ${HTTP_PROXY}
      # HTTPS_PROXY: ${HTTPS_PROXY}
      # NO_PROXY: ${NO_PROXY:-localhost,127.0.0.1}

volumes:
  app:
  uploads:
  data:
  mongodb:

info

The application listens on port 7077 by default. The host and container port must match, because ROOT_URL is used to generate absolute URLs served to clients.

note

The Operaide image is published for linux/amd64. On x86_64 Linux servers Docker selects it automatically. If you deploy on an ARM host (e.g. Apple Silicon or ARM Linux), add platform: linux/amd64 to the operaide service to run it under emulation.

Step 2: Configure Environment Variables

Create a .env file next to compose.yml:

# Required
TAG=operaide-v3.0
ROOT_URL=https://operaide.your-domain.com
PORT=7077
MAIL_URL=smtp://user:password@smtp.your-domain.com:587
MAIL_SENDER=Operaide <noreply@your-domain.com>

# Audit Service
OPERAIDE_AUDITING_TOKEN=oprd_your-token-here

# Optional
NO_REGISTRATION=false  # Set to 'true' to disable self-registration

# Proxy (optional — uncomment if behind a corporate proxy)
# HTTP_PROXY=http://proxy.company.com:8080
# HTTPS_PROXY=http://proxy.company.com:8080
# NO_PROXY=localhost,127.0.0.1,.internal.company.com

info

AI provider credentials (OpenAI, Azure OpenAI, Anthropic, etc.) and external connections (Firecrawl, ERP systems) are configured through the Operaide UI after installation — no environment variables needed.

Step 3: Start the Application

docker compose up -d

Step 4: Initial Setup

Open your browser and navigate to your ROOT_URL
Register the first user account
Assign System Admin and Super Admin roles via Profile menu (top right)
Configure organization settings under Settings

Step 5: Configure AI Provider

Navigate to AI Provider in the sidebar
Click Add Provider
Select your provider (Azure OpenAI, OpenAI, Anthropic, etc.)
Enter your API credentials
Test the connection and save

Step 6: Configure Connections (Optional)

Set up external system connections under Connections:

Web scraping services (e.g., Jina AI)
ERP systems
Custom APIs

Registration Settings

Control user registration via the NO_REGISTRATION environment variable:

Value	Behavior
`false`	Users can self-register (default)
`true`	Users must be invited by an admin

For fine-grained control, use the Automatic Registration regex pattern in organization settings.

Data Volumes

Volume	Container Path	Purpose
`mongodb`	`/mongodb`	Embedded MongoDB database files
`data`	`/data`	Studio workspaces, logs, user data
`uploads`	`/srv/uploads`	Uploaded documents
`app`	`/app/bundle/programs/server/assets/app/`	Application assets (organization logos, etc.)

warning

Always back up these volumes before updating Operaide. Use docker compose down (without -v) to preserve volumes when stopping the stack.

Backup

All persistent data lives in the four Docker volumes defined in compose.yml. Set up regular backups to protect against data loss.

Running a backup

Stop the stack before each backup run to ensure a consistent snapshot:

docker compose down
tar -czf operaide-backup-$(date +%F).tar.gz \
  /var/lib/docker/volumes/operaide_mongodb \
  /var/lib/docker/volumes/operaide_data \
  /var/lib/docker/volumes/operaide_uploads \
  /var/lib/docker/volumes/operaide_app
docker compose up -d

Store the resulting archive off-host — on a separate server, network share, or object storage.

tip

Automate this with a daily cron job. A weekly full backup plus daily incremental snapshots is a common starting point.

Updating Operaide

To update to a newer version:

Run a backup (see Backup above)
Update the TAG in your .env file
Pull the new image: docker compose pull
Restart: docker compose up -d

External MongoDB (Optional)

By default Operaide runs an embedded MongoDB inside the application container, using the mongodb volume for its data files. This is the simplest setup and fits most deployments.

If your environment requires a dedicated database — for example to reuse an existing managed MongoDB, run replica sets, or apply separate backup and monitoring policies — you can point Operaide at an external MongoDB instead.

Using a separate MongoDB container

Add a mongo service to your compose.yml and set MONGO_URL on the operaide service. When MONGO_URL is set, the embedded MongoDB is disabled and the mongodb volume is unused.

name: operaide
services:
  mongo:
    image: mongo:4.4
    restart: always
    volumes:
      - mongo:/data/db

  operaide:
    image: ghcr.io/objective-partner/op-no-gravity-operaide:${TAG}
    ports:
      - "${PORT:-7077}:${PORT:-7077}"
    restart: always
    depends_on:
      - mongo
    volumes:
      - app:/app/bundle/programs/server/assets/app/
      - uploads:/srv/uploads
      - data:/data
    environment:
      ROOT_URL: ${ROOT_URL}
      PORT: ${PORT:-7077}
      MONGO_URL: mongodb://mongo:27017/meteor
      NO_REGISTRATION: ${NO_REGISTRATION:-false}
      MAIL_URL: ${MAIL_URL}
      ENVCFG_MAIL_SENDER: ${MAIL_SENDER}
      METEOR_APP_ROOT: /srv
      OPERAIDE_AUDITING_TOKEN: ${OPERAIDE_AUDITING_TOKEN}
      OPERAIDE_AUDITING_URL: https://audit.operaide.ai
      OPERAIDE_AUDITING_ENABLED: "true"

volumes:
  mongo:
  app:
  uploads:
  data:

Using a managed MongoDB

Point MONGO_URL at the full connection string provided by your managed service — for example:

MONGO_URL=mongodb+srv://user:password@cluster.mongodb.net/meteor?retryWrites=true

warning

When using external MongoDB, its backup and restore is your responsibility. The Backup procedure above only covers the Docker volumes used by the Operaide container.

Troubleshooting

Container won't start

Check logs: docker compose logs operaide

Database problems

With the default embedded MongoDB, database files live in the mongodb volume and run inside the operaide container. Check the application logs for MongoDB errors:

docker compose logs operaide | grep -i mongo

If you run an External MongoDB, verify the mongo container is running and reachable:

docker compose ps
docker compose exec operaide curl -fsS mongo:27017 || echo "mongo unreachable"

AI Provider connection fails

Check credentials — verify your API key in AI Provider settings
Check network — ensure outbound HTTPS (port 443) is allowed to your provider's API endpoint (e.g., api.openai.com, api.anthropic.com)
If using a proxy — verify HTTP_PROXY / HTTPS_PROXY are set and the provider domain is not listed in NO_PROXY
Test from inside the container:

docker compose exec operaide curl -I https://api.openai.com

If the request fails, the issue is network-level connectivity, not Operaide configuration.

Audit service connection fails

Check environment variables:

docker compose exec operaide printenv | grep OPERAIDE_AUDITING

Ensure OPERAIDE_AUDITING_TOKEN is set correctly.

Test connectivity:

docker compose exec operaide curl -I https://audit.operaide.ai

If behind a corporate firewall, verify https://audit.operaide.ai is reachable or configure proxy settings (see Proxy Configuration).

System Requirements​

Minimum Hardware Requirements​

Additional Resources for Parallel Usage​

Per Parallel App Execution​

Per Operaide Studio Session​

Storage Considerations​

Software Requirements​

Supported Platforms​

Network Requirements​

Installation Identity​

Audit Service (Required)​

AI Provider APIs (Required for Configured Providers)​

External Integrations (Optional)​

Proxy Configuration​

Upstream NPM Registry​

Why an upstream registry​

Configuration​

Public upstream (default)​

Authenticated upstream​

Network requirements​

Common mistakes​

On-Premises Installation​

Step 1: Prepare Docker Compose​

Step 2: Configure Environment Variables​

Step 3: Start the Application​

Step 4: Initial Setup​

Step 5: Configure AI Provider​

Step 6: Configure Connections (Optional)​

Registration Settings​

Data Volumes​

Backup​

Running a backup​

Updating Operaide​

External MongoDB (Optional)​

Using a separate MongoDB container​

Using a managed MongoDB​

Troubleshooting​

Container won't start​

Database problems​

AI Provider connection fails​

Audit service connection fails​

System Requirements

Minimum Hardware Requirements

Additional Resources for Parallel Usage

Per Parallel App Execution

Per Operaide Studio Session

Storage Considerations

Software Requirements

Supported Platforms

Network Requirements

Installation Identity

Audit Service (Required)

AI Provider APIs (Required for Configured Providers)

External Integrations (Optional)

Proxy Configuration

Upstream NPM Registry

Why an upstream registry

Configuration

Public upstream (default)

Authenticated upstream

Network requirements

Common mistakes

On-Premises Installation

Step 1: Prepare Docker Compose

Step 2: Configure Environment Variables

Step 3: Start the Application

Step 4: Initial Setup

Step 5: Configure AI Provider

Step 6: Configure Connections (Optional)

Registration Settings

Data Volumes

Backup

Running a backup

Updating Operaide

External MongoDB (Optional)

Using a separate MongoDB container

Using a managed MongoDB

Troubleshooting

Container won't start

Database problems

AI Provider connection fails

Audit service connection fails