How to Set Up Nextcloud Office with Collabora Online (Complete Configuration Guide)

Editing documents inside a web browser without sending them to Google or Microsoft is one of Nextcloud's most compelling features, but it doesn't come built in. Nextcloud provides the file storage, sharing, and collaboration framework, while a separate document editing engine handles the actual rendering and editing of office files. The most mature and widely deployed option is Collabora Online, an open-source LibreOffice-based engine that handles .docx, .xlsx, .pptx, .odt, and dozens of other formats directly in the browser.

This guide covers the complete setup process, from choosing the right deployment model through production-ready Nginx reverse proxy configuration — which is where most deployments run into trouble. If you've been struggling with WOPI errors, blank document frames, or SSL handshake failures, you're in the right place.

Architecture Overview: How Nextcloud Office Works

Before diving into configuration, understanding the architecture prevents a lot of debugging pain later.

Nextcloud Office consists of three components working together:

• Nextcloud server: Stores files, manages users, handles sharing permissions, and serves the main web UI.
• Collabora Online (CODE or Enterprise): The document editing engine. This is a separate process (usually running in Docker) that renders documents in the browser using LibreOffice technology.
• WOPI protocol: Web Application Open Platform Interface — the communication layer between Nextcloud and Collabora. Nextcloud acts as the WOPI host (providing file access), and Collabora acts as the WOPI client (consuming and editing files).

When a user opens a document in Nextcloud, here is what happens:

1. Nextcloud generates a WOPI token and creates an iframe pointing to the Collabora server.
2. The user's browser loads the iframe, connecting directly to Collabora.
3. Collabora uses the WOPI token to request the file content from Nextcloud's WOPI endpoint.
4. Edits are sent from the browser to Collabora, which periodically saves changes back to Nextcloud via WOPI.

This means both the Collabora server and the user's browser need to reach the Nextcloud server, and the user's browser needs to reach the Collabora server. If any of these three network paths is broken (usually by reverse proxy misconfiguration, firewall rules, or SSL issues), document editing fails.

Collabora vs. ONLYOFFICE

Nextcloud supports two document editing backends: Collabora Online and ONLYOFFICE Document Server. Here is how they compare:

This guide focuses on Collabora Online because it is Nextcloud's official recommended editing engine and has the deepest integration. If you are considering Nextcloud as a replacement for Microsoft 365, Collabora provides the closest feature parity for document collaboration.

Choosing Your Deployment Model

Collabora Online can be deployed in three ways, each with different trade-offs:

Option 1: Built-in CODE (Nextcloud Office)

The simplest option. Install the "Nextcloud Office" app (which bundles CODE — Collabora Online Development Edition) directly within Nextcloud. No separate server, no Docker, no reverse proxy changes.

Best for: Personal use, small teams (under 5 concurrent editors), testing.

Limitations: Runs within the Nextcloud PHP process, so it shares resources. Performance degrades quickly with more than a few simultaneous document editors. Not recommended for production use with more than 10 users.

Option 2: Standalone Docker Container

Run Collabora Online as a Docker container on the same server as Nextcloud or on a separate server. This is the most common production deployment for small to mid-sized organizations.

Best for: Teams of 10-100 concurrent editors. Provides isolation from the Nextcloud process and allows independent resource allocation.

Option 3: Collabora Online Cluster

For large deployments, run multiple Collabora instances behind a load balancer. Collabora Online supports horizontal scaling, where each instance handles a subset of open documents.

Best for: Organizations with 100+ concurrent editors, or those requiring high availability for the document editing layer.

This guide covers Option 2 in detail, as it provides the best balance of simplicity and production readiness. If you have already completed our Nextcloud installation guide, you have the foundation needed to add Collabora.

Step-by-Step: Docker Deployment of Collabora Online

Step 1: Install Docker

If Docker isn't already installed on your server:

# Install Docker on Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

Step 2: Pull and Run the Collabora Online Container

The official Collabora Online Docker image is collabora/code. Run it with the following command, replacing the domain with your Nextcloud server's domain:

docker run -t -d \
  --name collabora \
  --restart always \
  -p 127.0.0.1:9980:9980 \
  -e "aliasgroup1=https://nextcloud.example.com:443" \
  -e "extra_params=--o:ssl.enable=false --o:ssl.termination=true" \
  -e "username=admin" \
  -e "password=YourSecureAdminPassword" \
  -e "server_name=collabora.example.com" \
  --cap-add MKNOD \
  collabora/code

Breaking down the important parameters:

• -p 127.0.0.1:9980:9980 — Binds port 9980 to localhost only. Collabora will be accessed through Nginx, never directly.
• aliasgroup1 — Tells Collabora which Nextcloud server(s) are allowed to connect via WOPI. This is a security measure: Collabora will refuse WOPI requests from domains not listed here. Use the full URL including port.
• extra_params — Disables SSL within the container (since Nginx handles TLS termination) and tells Collabora it's behind a TLS-terminating reverse proxy.
• username and password — Credentials for the Collabora admin console, accessible at https://collabora.example.com/browser/dist/admin/admin.html.

Verify the container is running:

docker logs collabora
# Look for: "Ready to accept connections on port 9980"

curl -s http://127.0.0.1:9980 | head -5
# Should return an XML capabilities response

Step 3: DNS Configuration

Create a DNS A record for your Collabora subdomain pointing to the same server (or a separate server if you're running Collabora elsewhere):

collabora.example.com    A    203.0.113.10

Nginx Reverse Proxy Configuration

This is the section where most Collabora deployments fail. The reverse proxy must correctly handle WebSocket upgrades, forward the right headers, and manage SSL termination. Here is a production-tested Nginx configuration:

server {
    listen 443 ssl http2;
    server_name collabora.example.com;

    ssl_certificate     /etc/letsencrypt/live/collabora.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/collabora.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Static files served by coolwsd
    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
    }

    # WOPI discovery
    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
    }

    # Capabilities
    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
    }

    # Main WebSocket endpoint — THIS IS CRITICAL
    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_read_timeout 36000s;
    }

    # Download, presentation, and image URLs
    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
    }

    # Admin console WebSocket
    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_read_timeout 36000s;
    }
}

The most common mistakes in this configuration:

• Missing WebSocket upgrade headers: The Upgrade and Connection headers on the /cool/.*/ws$ location are non-negotiable. Without them, the document editor loads but never connects, showing a spinning indicator forever.
• Wrong proxy timeout: The default Nginx proxy timeout is 60 seconds. Collabora keeps WebSocket connections open for hours. Set proxy_read_timeout to at least 36000 seconds (10 hours) on WebSocket locations.
• Missing Host header: If the Host header doesn't match the server_name configured in Collabora, WOPI token validation fails.
• SSL certificate issues: The Collabora subdomain needs its own valid TLS certificate. Use Let's Encrypt or your organization's CA.

Obtain a TLS certificate for the Collabora subdomain:

certbot certonly --nginx -d collabora.example.com

Test and reload Nginx:

nginx -t && systemctl reload nginx

Connecting Nextcloud to Collabora Online

With Collabora running and Nginx proxying requests, configure Nextcloud to use it:

1. Log into Nextcloud as an admin.
2. Navigate to Apps and install "Nextcloud Office" if not already installed.
3. Go to Administration Settings > Nextcloud Office.
4. Select "Use your own server".
5. Enter the Collabora URL: https://collabora.example.com
6. Click "Save" and wait for the green checkmark confirming connectivity.

If you see an error instead of a green checkmark, the most likely causes are:

• Collabora cannot reach Nextcloud (check the aliasgroup1 setting in the Docker command)
• SSL certificate validation failure (Collabora must trust the CA that signed Nextcloud's certificate)
• Firewall blocking port 9980 on localhost or port 443 between the servers

To test WOPI discovery from the Nextcloud server:

curl -s https://collabora.example.com/hosting/discovery | head -20

This should return an XML document listing supported file types and their action URLs. If it returns an error or empty response, the reverse proxy or Docker container is misconfigured.

Resource Sizing for Production

Collabora Online's resource requirements scale with the number of simultaneous open documents and active editors. Here are sizing recommendations based on real-world deployments:

Each open document consumes roughly 50-100 MB of RAM on the Collabora server, depending on document complexity. Spreadsheets with heavy calculations and presentations with many images consume more. The CPU impact comes primarily from rendering operations and real-time collaboration sync.

For accurate sizing of your specific workload, our Nextcloud performance tuning guide covers benchmarking techniques that apply to both the Nextcloud server and the Collabora backend.

Font Installation

One of the most common complaints after deploying Collabora is that documents look different than they do in Microsoft Office. This happens because Collabora renders documents using the fonts available inside its container, which may not include Microsoft's proprietary fonts (Arial, Times New Roman, Calibri, etc.).

To add custom fonts, mount a font directory into the Docker container:

# Create a fonts directory and copy your font files
mkdir -p /opt/collabora-fonts
cp /path/to/your/fonts/*.ttf /opt/collabora-fonts/
cp /path/to/your/fonts/*.otf /opt/collabora-fonts/

# Restart Collabora with the font mount
docker stop collabora && docker rm collabora

docker run -t -d \
  --name collabora \
  --restart always \
  -p 127.0.0.1:9980:9980 \
  -v /opt/collabora-fonts:/opt/cool/systemplate/tmpfonts:ro \
  -e "aliasgroup1=https://nextcloud.example.com:443" \
  -e "extra_params=--o:ssl.enable=false --o:ssl.termination=true" \
  -e "username=admin" \
  -e "password=YourSecureAdminPassword" \
  -e "server_name=collabora.example.com" \
  --cap-add MKNOD \
  collabora/code

Ensure you have the appropriate licenses for any proprietary fonts you install. For a license-free alternative, the Google Noto fonts family provides excellent coverage across scripts and closely matches common document fonts.

Performance Tuning

Once Collabora is running, several tuning parameters can improve responsiveness and reduce resource consumption:

Limit Maximum Documents and Users

Prevent the server from being overwhelmed by capping concurrent usage:

docker run -t -d \
  --name collabora \
  --restart always \
  -p 127.0.0.1:9980:9980 \
  -e "aliasgroup1=https://nextcloud.example.com:443" \
  -e "extra_params=--o:ssl.enable=false --o:ssl.termination=true \
      --o:num_prespawn_children=4 \
      --o:per_document.max_concurrency=4 \
      --o:per_document.idle_timeout_secs=3600 \
      --o:per_document.limit_file_size_mb=100" \
  -e "username=admin" \
  -e "password=YourSecureAdminPassword" \
  --cap-add MKNOD \
  collabora/code

Key tuning parameters:

• num_prespawn_children — Number of pre-forked child processes ready to handle new documents. Higher values reduce document open latency but consume more idle RAM. Set to 2-4 for most deployments.
• per_document.max_concurrency — Maximum concurrent editors per document. Limits resource usage for collaborative editing sessions.
• per_document.idle_timeout_secs — How long a document stays open in memory after the last editor closes it. Reduces memory usage but increases reopen latency. 3600 seconds (1 hour) is a reasonable default.
• per_document.limit_file_size_mb — Maximum file size that Collabora will attempt to open. Prevents out-of-memory crashes from extremely large files.

Docker Resource Limits

Constrain the container to prevent Collabora from consuming all server resources:

docker run -t -d \
  --name collabora \
  --restart always \
  --memory="4g" \
  --cpus="4" \
  -p 127.0.0.1:9980:9980 \
  -e "aliasgroup1=https://nextcloud.example.com:443" \
  -e "extra_params=--o:ssl.enable=false --o:ssl.termination=true" \
  -e "username=admin" \
  -e "password=YourSecureAdminPassword" \
  --cap-add MKNOD \
  collabora/code

Troubleshooting WOPI Failures

WOPI failures are the most common category of issue with Collabora + Nextcloud deployments. Here is a systematic troubleshooting approach:

Error: "Failed to load document"

1. Check Collabora logs: docker logs collabora — look for WOPI-related errors.
2. Check WOPI reachability: From the Collabora container, can it reach Nextcloud?

   docker exec collabora curl -s https://nextcloud.example.com/status.php

   If this fails, the issue is network connectivity between Collabora and Nextcloud.
3. Check aliasgroup: Ensure the aliasgroup1 environment variable exactly matches your Nextcloud URL, including the protocol and port.

Error: "WOPI host did not respond" or Blank Frame

This usually means the browser cannot reach the Collabora server:

1. Open your browser's developer console (F12) and check the Network tab for failed requests to collabora.example.com.
2. Verify DNS resolution: nslookup collabora.example.com from your workstation.
3. Test direct access: https://collabora.example.com/hosting/discovery should return XML in your browser.
4. Check for mixed content: if Nextcloud is on HTTPS, Collabora must also be on HTTPS.

Error: "Connection closed" After a Few Minutes

This is almost always a proxy timeout issue. Ensure proxy_read_timeout is set to at least 36000 seconds on all WebSocket locations in your Nginx configuration. If you're behind an additional load balancer or CDN, check its timeout settings as well.

Documents Open Slowly

If documents take more than a few seconds to open, check these factors in order:

1. Pre-spawn children: If num_prespawn_children is set to 0 or 1, every document open requires forking a new process. Increase this value to keep idle processes ready.
2. File size: Large files (50+ MB) naturally take longer to load. Consider the limit_file_size_mb parameter to prevent extremely large files from overwhelming the server.
3. Memory pressure: If the Collabora container is swapping, document opens become painfully slow. Monitor with docker stats collabora and increase the memory limit if utilization consistently exceeds 80%.
4. Network latency: If Collabora and Nextcloud are on different servers, WOPI file transfers add latency proportional to file size. Colocating them in the same data center minimizes this overhead.

Collaborative Editing Conflicts

When two users edit the same section of a document simultaneously, Collabora uses an operational transformation algorithm to merge changes. In rare cases, this can produce unexpected results. If users report "ghost" text or misplaced edits, ensure all parties are using a modern browser (Chrome 90+, Firefox 88+, Safari 15+, Edge 90+) and that there are no network intermediaries (corporate proxies, VPNs) interfering with WebSocket connections.

Enabling Specific File Types and Advanced Features

By default, Collabora handles the most common office formats, but you may want to customize which file types open in the editor versus being downloaded. Navigate to Administration Settings > Nextcloud Office to manage these associations.

Enabling PDF Editing

Collabora can open PDFs for annotation and basic editing. To enable this, check the "Use for PDF files" option in the Nextcloud Office settings. Note that PDF editing in Collabora is limited compared to purpose-built PDF editors — it works well for annotations, signatures, and simple text additions, but not for major structural changes to PDF layouts.

Setting Default Open Actions

You can configure whether files open for editing or viewing by default. For environments where most users consume documents rather than edit them, setting the default action to "view" reduces Collabora resource consumption since viewing mode is significantly lighter than edit mode.

Watermarking

Collabora supports document watermarking, which is useful for organizations handling confidential files. Configure watermarks through the extra_params in the Docker run command:

--o:watermark.enabled=true \
--o:watermark.text="CONFIDENTIAL - {user}" \
--o:watermark.opacity=0.2

The {user} placeholder is replaced with the logged-in user's display name, providing per-user accountability when documents are printed or screenshotted.

Monitoring and Health Checks

For production deployments, monitor Collabora's health to catch issues before users report them:

Built-in Admin Console

Access the admin console at https://collabora.example.com/browser/dist/admin/admin.html using the credentials you set in the Docker environment variables. The console shows:

• Number of currently open documents
• Active user count and per-document editor counts
• Memory consumption per document process
• CPU usage across document processes

Health Check Endpoint

Collabora exposes a health check endpoint that you can integrate with monitoring tools like Prometheus, Nagios, or simple cron-based checks:

# Basic health check
curl -s -o /dev/null -w "%{http_code}" https://collabora.example.com/hosting/capabilities

# Should return 200. Any other code indicates a problem.

For Docker health checks, add the --health-cmd parameter when starting the container:

docker run -t -d \
  --name collabora \
  --restart always \
  --health-cmd="curl -s -f http://localhost:9980/hosting/capabilities || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  -p 127.0.0.1:9980:9980 \
  -e "aliasgroup1=https://nextcloud.example.com:443" \
  -e "extra_params=--o:ssl.enable=false --o:ssl.termination=true" \
  -e "username=admin" \
  -e "password=YourSecureAdminPassword" \
  --cap-add MKNOD \
  collabora/code

Log Monitoring

Collabora logs are accessible via Docker's standard logging mechanism. For production, redirect them to your centralized logging system:

# View real-time logs
docker logs -f collabora

# Common log entries to watch for:
# - "Document loaded" — confirms successful file opens
# - "WOPI::GetFile" — shows WOPI file retrieval from Nextcloud
# - "Socket error" — indicates connectivity problems
# - "Kit process terminated" — document process crashed, may indicate resource constraints

Upgrading Collabora Online

Docker makes upgrades straightforward. Pull the latest image, stop the current container, and start a new one with the same parameters:

# Pull the latest image
docker pull collabora/code

# Stop and remove the existing container
docker stop collabora && docker rm collabora

# Start with the same configuration (adjust parameters as needed)
docker run -t -d \
  --name collabora \
  --restart always \
  -p 127.0.0.1:9980:9980 \
  -e "aliasgroup1=https://nextcloud.example.com:443" \
  -e "extra_params=--o:ssl.enable=false --o:ssl.termination=true" \
  -e "username=admin" \
  -e "password=YourSecureAdminPassword" \
  -e "server_name=collabora.example.com" \
  --cap-add MKNOD \
  collabora/code

Users with open documents will be disconnected during the upgrade — their changes are auto-saved before disconnection. Schedule upgrades during low-usage periods and announce them in advance. The total downtime is typically under 60 seconds.

Cost and Infrastructure Planning

Running Collabora Online adds infrastructure cost to your Nextcloud deployment, but it's typically a fraction of what per-user SaaS subscriptions cost. Consider the total cost of ownership: a 4-vCPU, 8 GB server dedicated to Collabora might cost around $40-60/month on dedicated infrastructure, supporting 50+ concurrent editors. That's less than $1 per user per month, compared to $12.50+ per user per month for Microsoft 365 Business Standard.

For organizations deploying Nextcloud as a complete collaboration platform, the Collabora component should be provisioned on infrastructure that can scale independently from the Nextcloud file server. Running both on the same server works for smaller teams, but as you scale beyond 50 users, separation lets you upgrade the Collabora server's CPU and RAM without affecting file storage operations.

MassiveGRID's managed Nextcloud hosting includes Collabora Online preconfigured and tuned for your team size, eliminating the reverse proxy configuration that causes most deployment failures. The infrastructure is sized based on your expected concurrent editor count, with the ability to scale up as your team grows. If you're evaluating Nextcloud Office for your organization, see how MassiveGRID's managed hosting simplifies what would otherwise be a multi-day configuration project into a deployment you can start using immediately.