ON-Prem Installation Guide

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

Two deployment paths are available. See Deployment for the choice.

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.

Native proxy mode

Operaide configures proxy handling itself by default. On Node.js 24.5+ you can hand this to Node instead: set NODE_USE_ENV_PROXY=1. Operaide then skips its own proxy setup and Node parses HTTP_PROXY, HTTPS_PROXY, and NO_PROXY directly. Leave it unset unless you have a specific reason to use native mode.

---

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 upstream token with the per-user keys that authenticate developers to this instance's registry. The upstream token authenticates this instance to the upstream; developers authenticate themselves to this instance with their own personal token (see App Store: Publishing).

---

Runtime Configuration

Optional environment variables that tune a running instance. All have working defaults; set them only when you need to change the default behavior.

Health monitoring and auto-restart

Operaide can restart itself when the server stops responding. Set HEALTH_CHECK_TIMEOUT to enable it. Unset (the default) means no monitoring.

Variable	Purpose	Default
HEALTH_CHECK_TIMEOUT	Seconds a /health request may take before the instance counts as deadlocked. Empty disables monitoring.	unset (disabled)
HEALTH_CHECK_STARTUP_TIMEOUT	Seconds to wait for the server to come up before monitoring starts.	60

Restarts are throttled to 5 per 60-second window, with a 5-second delay between them. These limits are fixed and cannot be changed.

Content Security Policy

Operaide sends a restrictive Content-Security-Policy header by default: default-src 'self', with blob: and data: exceptions for workers, frames, scripts, and images. Change it only when an App must load resources from another origin.

Variable	Purpose
CONTENT_SECURITY_POLICY	Replaces the entire default policy. Provide the full header value.
CONTENT_SECURITY_POLICY_ADDITIONAL	Appended to the active policy. Adds directives without rewriting the default.

warning

CONTENT_SECURITY_POLICY replaces the default in full. A value that is too narrow breaks the UI. To add a single source, prefer CONTENT_SECURITY_POLICY_ADDITIONAL.

Embedded MongoDB cache

The embedded MongoDB uses a WiredTiger cache of 0.25 GB by default. Raise MONGO_CACHE_SIZE_GB on instances with heavy database use and spare RAM. It has no effect when you run an External MongoDB (MONGO_URL set).

Studio session timeout

An Operaide Studio session times out after 30 minutes by default. Adjust it with WORKBENCH_SESSION_TIMEOUT_MINUTES.

---

Deployment

Choose one path. Both produce a running Operaide container that meets the audit, AI, proxy, and NPM requirements above.

• Automatic Deployment: one curl ... | bash command runs the installer. It asks for the install location, registry login, optional Caddy reverse proxy and TLS, audit token, and SSO, then starts the instance. Updates run via operaide self-update.
• Manual Deployment: write your own compose.yml and .env, then run docker compose up. Use this when you need full control: external MongoDB, custom networking, or organization-specific compose conventions.

---

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. See the Backup and Restore section for the supported backup workflow.

---

Backup

Operaide ships a built-in backup system that captures MongoDB, the data volume, the SQLite agent databases, the operator-uploaded logos and documents, and the container image into one tar file. Restore on a fresh host runs from one command.

See the Backup and Restore section for the full setup, transport options (rsync, S3, SCP, BYO), restore procedure, and recovery drill.

---

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. The automatic installer always uses the embedded database; external MongoDB requires Manual Deployment.

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

  app:
    image: ${OPERAIDE_IMAGE}:${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

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 and Restore section covers the Operaide-managed volumes; the external database needs its own snapshot policy.

---

Troubleshooting

Container won't start

Check logs: docker compose logs app

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 app | grep -i mongo

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

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

AI Provider connection fails

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

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

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

Audit service connection fails

1. Check environment variables:

docker compose exec app printenv | grep OPERAIDE_AUDITING

Ensure OPERAIDE_AUDITING_TOKEN is set correctly.

2. Test connectivity:

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

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