Skip to content
API documentationv1

Self-hosting

Self-hosting Beta

Machine requirements, ports, host names, TLS certificates and the commands to try O3O Office Online on Docker in a few minutes.

This page describes a beta feature: it works but may still change.

On this page

This page brings O3O Office Online up on a Docker host: machine requirements, ports, host names, certificates and the commands for a first run in a few minutes. Every service and environment variable is described in Compose file and environment variables.

Machine requirements#

ItemRequirementNotes
DockerDocker Engine on Linux, or Docker Desktop with the Linux engine; Docker Compose v2 (the docker compose command)Verified on Docker Desktop 29, Linux engine.
CPU architecturex86_64 (amd64)Other architectures: not tested.
CPU and RAM for a test machineSuggested minimum 4 cores, 8 GB of RAM for DockerSizing per number of connections: not measured yet.
DiskSuggested 25 GB free for images and dataData lives in Docker volumes.
WindowsDocker Desktop with WSL2WSL2 only uses part of the machine's RAM by default; raise the limit in .wslconfig if containers get killed for lack of memory.

Ports#

PortServicePublishedNotes
8080 (O3O_PROXY_PORT)o3o-proxyyesThe single entry point, HTTP.
8081 (O3O_NEXTCLOUD_PORT)o3o-nextcloudyes, nextcloud profile onlyFor trying the Nextcloud integration.
9980o3o-onlinenoEditing server; only the proxy and the gate talk to it.
8070o3o-gatenoReached through the proxy at /o3o/.
8060o3o-docbuildernoReached through the proxy at /v1/.
3306, 6379o3o-nextcloud-db, o3o-nextcloud-redisnonextcloud profile only.

When another service already holds port 8080 or 8081, change O3O_PROXY_PORT or O3O_NEXTCLOUD_PORT, then update O3O_PUBLIC_URL and O3O_ONLINE_SERVER_NAME to match.

First run in a few minutes#

BashBuild and run (Linux, macOS or Git Bash on Windows)
# 1. Get the O3O Office sources (the online/ folder holds the Docker bundle)
git clone <O3O Office repository URL> o3o-office
cd o3o-office

# 2. Build the gate and DocBuilder images; the build context is always online/
docker build -f online/gate/Dockerfile -t o3o/gate:dev online
docker build -f online/docbuilder/Dockerfile -t o3o/docbuilder:dev online

# 3. Create .env for a DEV machine: the script copies .env.example and replaces every CHANGE_ME with a random string (PowerShell: scripts\gen-secrets.ps1 -Dev)
cd online
bash scripts/gen-secrets.sh --dev

# 4. Start
docker compose --env-file .env -f docker/compose.dev.yml up -d
docker compose --env-file .env -f docker/compose.dev.yml ps

# 5. Check
curl -s http://localhost:8080/o3o/healthz
curl -s http://localhost:8080/o3o/status | jq '{edition, dev_image, upstream, connections: .connections.enforcing}'
curl -s http://localhost:8080/v1/status | jq '{version, core, workers}'
  • The editing server needs roughly 10 to 20 seconds to become ready; until then /o3o/status may report upstream.coolwsd = "down".
  • The secret generator is mandatory: the nextcloud profile cannot start while .env still contains CHANGE_ME.
  • --dev sets O3O_DEV_MODE=1 and O3O_EMBED_ALLOW_UNSIGNED=1: open http://localhost:8080/o3o/demo to try the embedded editor on a sample file. Without --dev, .env keeps the sample file's safe values (both 0); use that on production machines.
  • Run the script with bash, not sh: it uses bash syntax.

Adding Nextcloud to try the integration#

BashThe nextcloud profile
cd online
DC="docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud"

# Start with Nextcloud, MariaDB and Redis
$DC up -d

# Wait until it returns "installed": true
curl -s http://localhost:8081/status.php

# Quick way: the script runs every step below, then creates a test user and sample files
bash scripts/setup-nextcloud.sh

# Or by hand (DEV machine only). Always pass --callback-url: without it activate-config resets wopi_callback_url to empty
$DC exec -u www-data o3o-nextcloud php occ app:install richdocuments
$DC exec -u www-data o3o-nextcloud php occ config:app:set richdocuments wopi_allowlist --value=""
$DC exec -u www-data o3o-nextcloud php occ config:app:set richdocuments disable_certificate_verification --value=yes
$DC exec -u www-data o3o-nextcloud php occ richdocuments:activate-config \
    --wopi-url=http://o3o-online:9980 --callback-url=http://o3o-nextcloud

# Must be http://localhost:8080 (richdocuments derives it from discovery; never set it by hand)
$DC exec -u www-data o3o-nextcloud php occ config:app:get richdocuments public_wopi_url

Host names and DNS#

  • O3O_ONLINE_SERVER_NAME is the public host[:port] users type; it decides the editor path in /hosting/discovery. O3O_PUBLIC_URL is the matching scheme://host[:port], without a trailing /.
  • The file store (for example Nextcloud) must produce a WOPISrc that the o3o-online CONTAINER can reach. localhost inside a container is the container itself: use the internal service name (http://o3o-nextcloud) or host.docker.internal.
  • O3O_ONLINE_ALIASGROUP2 must contain the exact origin of the WOPISrc. Items after the comma are regular expressions: write dots as \..
  • An embedding page on another origin: set O3O_ONLINE_FRAME_ANCESTORS (a single value, no spaces).

TLS certificates#

o3o-proxy only listens on HTTP. Certificates live on the outer proxy (nginx, Traefik or a load balancer) in front of port 8080; the editing server always runs with ssl.enable=false. When users arrive over https, set all three variables:

BashVariables for https
O3O_PUBLIC_URL=https://office.example.com
O3O_ONLINE_SERVER_NAME=office.example.com
O3O_ONLINE_SSL_TERMINATION=true

Outer proxy samples with WebSocket support: Reverse proxy. Calls between containers (WOPI, internal callbacks) use http inside the Docker network, so they need no certificate of their own.

Compose file and environment variablesEvery service, every variable.Reverse proxynginx and Traefik in front of O3O, with WebSocket.Production securityThe checklist before opening to users.MonitoringHealth checks, logs, figures.

Report a problem or suggest an editO3O Office Online · API v1 · Page version 26.8.6