How to Integrate ONLYOFFICE with Nextcloud: Setup Guide

ONLYOFFICE integrates with Nextcloud through two main components: the connector app and a separate Document Server. The Document Server handles all document edits in real-time; the Nextcloud connector bridges the web interface to the Server. Setup takes 20-30 minutes with Docker. This guide covers the complete installation, from deployment through security configuration.

Why Integrate ONLYOFFICE with Nextcloud?

ONLYOFFICE brings Microsoft Office compatibility and superior performance to Nextcloud's document editing stack. Nextcloud Office, built on LibreOffice, handles basic editing well but stumbles with complex formatting, macros, and Excel compatibility. ONLYOFFICE Docs renders.docx,.xlsx, and.pptx files exactly as Microsoft does, then sends edits back to Nextcloud losslessly.

Performance matters. Nextcloud Office runs the editor on the same Nextcloud server as your files, eating CPU and RAM. ONLYOFFICE offloads editing to a dedicated Document Server, leaving Nextcloud to handle storage and authentication. For teams editing simultaneously, this separation is critical. One server doesn't bog down the other.

Real-time collaboration is smooth. Multiple users can edit the same document without stepping on each other's changes. Comments, tracked changes, and revision history work like Office. If you're moving off Microsoft 365 or Google Workspace, ONLYOFFICE is the closest match. See our comparison of Nextcloud Office vs ONLYOFFICE for a detailed breakdown of features.

Two Deployment Models: Dedicated vs Community Document Server

ONLYOFFICE ships two ways: Community Document Server (lighter, free) and Dedicated Document Server (more robust, paid features). The community version is fully functional and open-source (AGPL-3.0). Most self-hosted setups use it. The dedicated version adds user management, document encryption, and branding tools, but costs money and requires a separate license.

Choose Community if: you're testing the setup, your team has under 20 concurrent users, or you want zero licensing overhead. Community runs on a 2-core VM with 2 GB RAM and handles light-to-moderate loads well. The limit of up to 20 concurrent users is soft; you can push it higher, but performance degrades.

Choose Dedicated if: you have 50+ concurrent users, need high availability, or plan to integrate ONLYOFFICE across multiple Nextcloud instances. Dedicated includes clustering, load balancing, and Docservice scaling. It's more infrastructure, but it's designed for enterprise workloads. For this guide, we cover Community Document Server. The installation steps are identical for Dedicated; the only differences are licensing and admin features.

Check Your System Requirements

Before you start, verify your hardware. ONLYOFFICE is lighter than you might think, but undersizing causes mysterious timeout errors and slow edits. The Document Server and Nextcloud can run on the same machine, but they compete for resources.

Minimum specs: 2 CPU cores, 2 GB RAM, 10 GB disk (for documents). Recommended for production: 4 cores, 4 GB RAM, 50+ GB disk. If you're running Nextcloud and Document Server on the same VM, add their requirements together. Nextcloud itself needs 2 cores and 2 GB; ONLYOFFICE needs another 2 cores and 2 GB. A single 4-core, 4 GB machine is the bare minimum for both.

Network matters. Nextcloud and Document Server must reach each other with low latency (under 10 ms is ideal, under 100 ms is acceptable). If they're on different networks, firewall rules must allow port 8443 (HTTPS) or 80 (HTTP) between them. Document Server doesn't require internet access; it only talks to Nextcloud.

Step 1: Deploy the Document Server (Docker)

Docker is the path of least resistance. You avoid OS-specific package managers, configuration drift, and dependency hell. We'll use the official ONLYOFFICE docker-onlyoffice-nextcloud image (761 GitHub stars, actively maintained).

First, pull the image: docker pull onlyoffice/documentserver:latest. This downloads the latest stable release. The image is ~800 MB; give it a minute depending on your connection.

Next, run the container. If you're on a single machine and don't need SSL immediately, start with:

docker run -d --name onlyoffice-documentserver \
  -p 8443:443 \
  -v /opt/onlyoffice/data:/var/www/onlyoffice/Data \
  -v /opt/onlyoffice/log:/var/log/onlyoffice \
  onlyoffice/documentserver:latest

This: binds port 8443 on your host to 443 inside the container (HTTPS), mounts data and logs to /opt/onlyoffice (so they survive container restarts), and names the container onlyoffice-documentserver for easy management.

Wait 30 seconds for the container to start, then check: docker logs onlyoffice-documentserver. You should see "Starting supervisor" with no errors. Visit your Document Server at localhost:8443 in your browser (if running on the same machine). You'll see a self-signed certificate warning; accept it. The page should load without errors.

For production, you need a real SSL certificate, not self-signed. Use Let's Encrypt with certbot. Install certbot: apt-get install certbot python3-certbot-nginx (or your distro's equivalent). Run certbot certonly --standalone -d yourdomain.com and follow the prompts. Certbot saves the cert and key to /etc/letsencrypt/live/yourdomain.com/. Mount these into the container:

docker run -d --name onlyoffice-documentserver \
  -p 8443:443 \
  -e SSL_CERTIFICATE_PATH=/etc/ssl/certs/cert.pem \
  -e SSL_KEY_PATH=/etc/ssl/private/key.pem \
  -v /opt/onlyoffice/data:/var/www/onlyoffice/Data \
  -v /opt/onlyoffice/log:/var/log/onlyoffice \
  -v /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/ssl/certs/cert.pem:ro \
  -v /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/ssl/private/key.pem:ro \
  onlyoffice/documentserver:latest

The :ro flag makes the mounts read-only (safer). Certbot auto-renews certificates, and the container will pick up new certs on restart.

Step 2: Install the ONLYOFFICE Connector in Nextcloud

Log in to Nextcloud as admin. Click your profile icon (top right), then "Apps". In the search bar, type "ONLYOFFICE". The official connector (by Ascensio System SIA, the company behind ONLYOFFICE) should appear first. Click "Install".

Wait 10-20 seconds. The page reloads, and the app is enabled. You'll see it listed under "Enabled apps" with a description: "ONLYOFFICE connector allows you to view, edit and collaborate on text documents, spreadsheets, and presentations in Nextcloud."

This app is small and lightweight; it's just a bridge. It doesn't process documents. It translates Nextcloud's file requests into calls to the Document Server and returns the results. Think of it as a proxy that understands both Nextcloud's REST API and ONLYOFFICE's JavaScript SDK. You're not done yet. The connector is installed but not configured. It doesn't know where your Document Server is. That's the next step.

Step 3: Configure the Connection

After installation, the ONLYOFFICE settings appear in Nextcloud. Click your profile icon, then "Administration" (if you're admin). In the left sidebar under "ONLYOFFICE" (you might need to scroll), click "Settings".

You'll see a form with three fields: "ONLYOFFICE Server address", "Secret key (JWT)", and "Edit in browser" checkbox. Start with the server address. This is the URL of your Document Server, as seen by Nextcloud.

If Document Server is on the same machine as Nextcloud, enter localhost or 127.0.0.1 on port 8443. If it's on a different machine, enter the internal IP address and port (for example, 192.168.1.10:8443 if Document Server is at that IP). If it's on a different server with a real domain, enter the domain name on port 8443 (for example, docs.yourdomain.com:8443, assuming you set up a reverse proxy or port forwarding).

Important: ONLYOFFICE requires HTTPS. HTTP will fail with a 403 Forbidden error. This is a security feature, not a bug. If you see 403 when you try to edit a document, the first thing to check is the certificate. Does Document Server have a valid cert? Can Nextcloud reach it on HTTPS without certificate verification errors?

To test the connection: on the Nextcloud machine, run curl -k against your Document Server URL (replacing your-documentserver-address with your actual server hostname or IP, and add :8443 for the port). The -k flag ignores certificate errors for testing. If you get a response (not a timeout or connection refused), the server is reachable.

Once you've entered the server address, you can leave the secret key blank for now. Click "Save". Open a document in Nextcloud (create a test.docx file or upload one) and click it. If you see the ONLYOFFICE editor load, your basic setup works.

Step 4: Set Up JWT Security

If you're testing locally or on a private network, JWT isn't strictly necessary. In production, JWT is essential. It prevents unauthorized access to the Document Server from outside your network.

JWT stands for JSON Web Token. It's a signed token that proves Nextcloud sent the request, not some attacker. When you edit a document, Nextcloud generates a JWT token containing your user ID, the file name, and the document ID, then signs it with a secret key. The token is sent to Document Server. Document Server verifies the signature using the same secret key. If the signature matches, the request is valid. If someone forges or modifies the token, the signature fails, and Document Server rejects the request.

To enable JWT: Generate a secret key. A random string of 32+ characters works: openssl rand -hex 16 produces a good one. Copy the output. In Nextcloud, go back to ONLYOFFICE Settings and paste the secret into the "Secret key (JWT)" field. Save.

Then configure the same secret in Document Server. This is an environment variable or a config file. The easiest way: include it when you start the Docker container with -e JWT_SECRET=yoursecretkey. If the container is already running, you'll need to stop it, set the variable, and restart:

docker stop onlyoffice-documentserver
docker rm onlyoffice-documentserver
docker run -d --name onlyoffice-documentserver \
  -p 8443:443 \
  -e JWT_SECRET=yoursecretkey \
  -e SSL_CERTIFICATE_PATH=/etc/ssl/certs/cert.pem \
  -e SSL_KEY_PATH=/etc/ssl/private/key.pem \
  -v /opt/onlyoffice/data:/var/www/onlyoffice/Data \
  -v /opt/onlyoffice/log:/var/log/onlyoffice \
  -v /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/ssl/certs/cert.pem:ro \
  -v /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/ssl/private/key.pem:ro \
  onlyoffice/documentserver:latest

After restart, test again. Open a document. If it loads, JWT is working.

Troubleshooting Common Issues

403 Forbidden when clicking a document: This is the most common error. The document won't open in ONLYOFFICE; you get a browser error instead. The cause is almost always a certificate mismatch. Check: Can Nextcloud reach Document Server on HTTPS without certificate errors? From the Nextcloud machine, use curl with the verbose flag to check the connection. Look for errors like "SSL certificate verify failed". If you see this, the certificate is invalid or self-signed. Either replace it with a valid Let's Encrypt certificate, or configure Nextcloud to skip certificate verification (not recommended for production, but useful for testing): In Nextcloud's config.php, add: 'onlyoffice' => array ( 'verify_peer_off' => true, ),. Restart Nextcloud (if using PHP-FPM: systemctl restart php*-fpm), and test again.

Connection timeout: Document Server is running but Nextcloud can't reach it. Causes: firewall blocks the port, wrong IP/hostname, or Document Server isn't actually running. Check: Is Document Server running? docker ps | grep onlyoffice. If nothing appears, it crashed. Check logs: docker logs onlyoffice-documentserver. Look for errors like "address already in use" (port 8443 is taken) or out-of-memory (VM needs more RAM). Is the port open? netstat -ln | grep 8443 (on the Document Server machine) should show the port listening. On a different network, check firewall rules. If Document Server is behind a firewall or NAT, make sure port 8443 is forwarded.

JWT secret mismatch: You configured different secrets in Nextcloud and Document Server. Symptom: editor loads but edits don't save, or you get a "401 Unauthorized" error in the browser console. Fix: Verify both have the same secret. In Nextcloud, run ./occ config:get onlyoffice secret_key. In Document Server, check the JWT_SECRET environment variable: docker inspect onlyoffice-documentserver | grep JWT_SECRET.

External storage not supported: You're trying to edit a file on a mounted SMB, NFS, or S3 share. ONLYOFFICE doesn't support this; it needs files in Nextcloud's native storage backend. This is a known limitation mentioned in the official docs. Workaround: Copy the file to native Nextcloud storage, edit it, then move it back. Or upgrade to ONLYOFFICE Enterprise, which has better external storage support.

Next Steps: Running ONLYOFFICE in Production

Your setup is working locally. To run it in production, harden the environment: use persistent volumes so data survives container restarts, set up monitoring and log aggregation, and plan for scaling.

Move data and logs to persistent directories on your host. We already did this in Step 1 with -v /opt/onlyoffice/data:/var/www/onlyoffice/Data. Make sure this directory is backed up. If your VM dies, you lose everything outside persistent volumes.

Configure backups. Nextcloud files should be backed up by your host backup system. Document Server's data directory (/opt/onlyoffice/data) doesn't store documents; it stores temporary editing sessions. Lose it, and you lose in-progress work, but no permanent files. Still, back it up. Monitor disk usage. Document editing creates temporary files. If /opt/onlyoffice/data fills your disk, the server will hang. Set up a cron job to clean old temp files, or use a host-level monitoring tool to alert you when usage exceeds 80%.

Plan upgrades. ONLYOFFICE releases updates frequently. When you upgrade to a new version, pull the new Docker image and restart the container. Most upgrades are backward-compatible. Explore the best Nextcloud apps to extend your setup with additional integrations.

Consider managed hosting. If you want ONLYOFFICE and Nextcloud fully integrated and maintained by experts, check out Opsily's Nextcloud hosting. We handle the infrastructure, updates, security, and backups so you don't have to.

Frequently Asked Questions

What's the difference between ONLYOFFICE and Nextcloud Office?

Nextcloud Office is built on LibreOffice. It runs on your Nextcloud server and handles basic editing. ONLYOFFICE is a separate, dedicated editor focused on Microsoft Office compatibility. ONLYOFFICE renders and edits.docx,.xlsx, and.pptx files pixel-for-pixel like Microsoft does. Nextcloud Office is simpler to set up (no extra server needed) but less compatible with Office file formats. Choose ONLYOFFICE if Office compatibility and performance matter; choose Nextcloud Office if you want simplicity.

Is ONLYOFFICE free?

Yes. The Community Document Server is free and open-source (AGPL-3.0). You can deploy unlimited instances and edit unlimited documents. Enterprise features (user management, encryption, branding) are sold separately, but most self-hosted deployments use Community.

Can I run ONLYOFFICE and Nextcloud on the same server?

Yes, if you have enough resources. Nextcloud needs 2 cores and 2 GB RAM; ONLYOFFICE needs another 2 cores and 2 GB. A single 4-core, 4 GB machine handles both. For better performance and isolation, run them on separate VMs or containers.

Why does ONLYOFFICE need JWT if I'm on a private network?

JWT isn't about network security; it's about application security. Without JWT, anyone who knows your Document Server's URL can send edit requests without Nextcloud validating them. JWT ensures only your Nextcloud instance can trigger edits. In production, always enable JWT.

How do I know if my setup is working?

Upload a test Word document to Nextcloud and click it. If the ONLYOFFICE editor loads and you can type and save, it works. If you get a 403, 401, or blank page, check the troubleshooting section above.

Can ONLYOFFICE work offline?

No. ONLYOFFICE is a browser-based editor that requires a live connection to Document Server. You can't edit documents offline. Mobile apps exist (iOS and Android) but also require a connection. If offline editing is critical, stick with LibreOffice or Microsoft Office.

What does the ONLYOFFICE Nextcloud connector do?

It's middleware. When you click a document in Nextcloud, the connector loads a preview and creates a secure session. It tells the browser to open the ONLYOFFICE editor, passing the document's ID and a JWT token. The editor communicates directly with Document Server from there. The connector doesn't edit documents; it orchestrates the handshake.

The Bottom Line

ONLYOFFICE turns Nextcloud into a viable alternative to Google Workspace or Microsoft 365 for document collaboration. Setup takes 30 minutes with Docker, and the system scales from solo developers to teams of 100+. If Office compatibility matters and your team is larger than five people, ONLYOFFICE is worth the effort. Ready to run Nextcloud and ONLYOFFICE reliably? Get started with Opsily's managed Nextcloud hosting.