OnlyOffice 9.4 Lightweight Mode: One-Command Docker Deployment for Self-Hosted Docs

Preface

On May 19, 2026, OnlyOffice DocumentServer 9.4.0 was released with a landmark change: the community edition now enforces lightweight mode, dropping the previous standard mode. The traditional distributed architecture (Nginx + PostgreSQL + RabbitMQ + multiple Node processes) has been merged into a single-process monolithic architecture. Deploying an online document editing service shifts from docker-compose multi-container orchestration to a single docker run command.

1. What Is OnlyOffice?

Some may ask: "Isn't OnlyOffice just an open-source office suite? How does it differ from LibreOffice?"

The difference is significant. LibreOffice is desktop software installed locally for editing local files; its online variant is Collabora Online, built on the LibreOffice core. OnlyOffice's core is DocumentServer — an independent online document editing backend service. Think of it as a "cloud Office" running on your server, accessed via browser, with documents stored on your infrastructure, never touching third parties.

In plain terms: OnlyOffice is a "document editing backend service," not a complete cloud drive or office suite. It handles rendering and editing in the browser; document storage, permissions, and folder management must be provided by your system.

2. OnlyOffice Architecture at a Glance

The document manager and document storage service are provided by the integrator — either OnlyOffice DocSpace or your own implementation. DocumentServer handles editing, conversion, command, and build services.

3. Core Principles

document.key — The Identity Card of Collaborative Editing

This is the most critical concept for understanding OnlyOffice. Many developers initially assume the browser directly edits the Word file on the server. That is not the case.

The real flow:

The browser edits the collaborative editing file (Editor.bin) cached inside OnlyOffice , not the original Word file.

document.key is the unique identity of the current document content version. It is not a file ID; it is the current collaborative editing version ID . It determines five things: whether multiple users join the same collaborative session, whether an existing Editor.bin is reused, whether the file is considered changed, whether the original file is re-downloaded, and whether users belong to the same editing version.

Complete Editing Lifecycle

First open (key = key0) → original Word file downloaded → converted to Editor.bin cached in /var/lib/onlyoffice/documentserver/App_Data.

Multiple users join collaborative editing → same key0 → same collaborative session, all editing Editor.bin.

During editing → all changes stay in cache; the original Word file may remain unchanged.

The new Word file is generated only after all users exit editing or a forced save occurs , producing output.docx; the callback receives status = 2 or 6.

Why "Content Loss" Appears

Many systems receive the callback but fail to download output.docx, retaining the old original file. On next open, OnlyOffice downloads the stale file again. It is not content loss; the new output.docx was never saved.

4. Java Integration with OnlyOffice

4.1 Deploy DocumentServer

docker run -i -t -d -p 8080:80 --restart=always 
  -e JWT_ENABLED=true 
  -e JWT_SECRET='your-secret-key' 
  onlyoffice/documentserver:9.4.0

Visit http://localhost:8080 to verify.

4.2 Spring Boot Backend: Generate Editor Configuration

@RestController
public class DocumentController {
    @Value("${onlyoffice.docserver.url}")
    private String docServerUrl;

    @Value("${onlyoffice.callback.url}")
    private String callbackUrl;

    @GetMapping("/edit/{docId}")
    public String editDocument(@PathVariable String docId, Model model) {
        Document doc = documentService.findById(docId);

        // Build editor configuration
        Map<String, Object> config = Map.of(
            "document", Map.of(
                "fileType", doc.getExtension(),
                "key", doc.getVersionKey(),  // Critical! Must change key when content changes
                "title", doc.getName(),
                "url", doc.getDownloadUrl()
            ),
            "editorConfig", Map.of(
                "callbackUrl", callbackUrl,
                "mode", "edit",
                "user", Map.of(
                    "id", "1",
                    "name", "老张"
                )
            )
        );

        model.addAttribute("config", config);
        model.addAttribute("docServerUrl", docServerUrl);
        return "editor";
    }
}

Key point: key must be updated every time document content changes; otherwise OnlyOffice assumes the file is unchanged and continues using the cached Editor.bin.

4.3 Handle Save Callback

OnlyOffice callbacks your service on save:

@PostMapping("/callback")
@ResponseBody
public String handleCallback(@RequestBody Map<String, Object> data) {
    // Status 2 or 6 means document ready to save
    if ("2".equals(data.get("status")) || "6".equals(data.get("status"))) {
        String downloadUrl = (String) ((Map) data.get("url")).get("url");
        // Download and save document
        saveDocument(downloadUrl, (String) data.get("key"));
        // Update version key so next open reloads
        documentService.updateVersionKey((String) data.get("key"));
    }
    return "{\"error\":0}";
}

4.4 Frontend Page

<script src="http://docserver-url/web-apps/apps/api/documents/api.js"></script>
<div id="editor"></div>
<script>
const docEditor = new DocsAPI.DocEditor(
    "editor", {
        document: { fileType: "docx", key: "key0", title: "demo.docx", url: "..." },
        editorConfig: { callbackUrl: "http://your-server/callback", mode: "edit" },
        width: "100%", height: "100%"
    }
);
</script>

5. Lightweight Mode (9.4+)

This is the most important change in version 9.4.

Traditional standard mode relies on Nginx + PostgreSQL + RabbitMQ + multiple Node processes , requiring service dependency ordering, health checks, and MQ failure recovery. For SMEs, Docker single-container/NAS/Synology/ARM low-spec machines, and POC scenarios, these dependencies are too heavy.

Lightweight mode merges the distributed architecture dependent on message queues and databases into a single-process monolithic architecture . State is entirely in-memory, no extra database maintenance; single-machine file state management, no RabbitMQ dependency.

Comparison: Standard vs Lightweight

Dependencies: Standard — Nginx + PostgreSQL + RabbitMQ + multi-process; Lightweight — single-process monolith.

Deployment: Standard — docker-compose multi-container; Lightweight — docker run one-command.

Resource usage: Standard — high (MQ + DB resident memory); Lightweight — low.

Operational complexity: Standard — high; Lightweight — low.

Suitable scenarios: Standard — high-concurrency large-scale clusters; Lightweight — SMEs, small teams, POC.

Enable lightweight mode by adding an environment variable:

docker run -itd -p 8080:80 
  -e MEMORY_MODE=true 
  onlyoffice/documentserver:9.4.0

Lightweight mode is especially suitable for SME/small team document collaboration, POC verification and development testing, NAS/Docker single-container deployment, ARM low-spec machines, offline intranet environments. If your business requires clustering, high availability, or horizontal scaling, the standard mode is still recommended.

6. Comparative Analysis

OnlyOffice vs Collabora Online vs Microsoft 365

Core engine: OnlyOffice — custom OOXML engine; Collabora — LibreOffice core; Microsoft 365 — Microsoft native.

Native format: OnlyOffice — OOXML (.docx/.xlsx/.pptx); Collabora — ODF; Microsoft 365 — OOXML.

Microsoft format compatibility: OnlyOffice — strongest; Collabora — average; Microsoft 365 — native.

Deployment: OnlyOffice — Docker/Linux/Windows; Collabora — Docker/Linux; Microsoft 365 — cloud only.

Private deployment: OnlyOffice — ✅; Collabora — ✅; Microsoft 365 — ❌.

Idle memory: OnlyOffice — ~2GB; Collabora — ~1GB; Microsoft 365 — N/A.

Free tier limits: OnlyOffice — 20 concurrent connections; Collabora — 20 documents / 10 connections; Microsoft 365 — no free tier.

Collaborative editing: All three support real-time co-editing.

AI assistant: OnlyOffice — ✅ built-in (supports DeepSeek etc.); Collabora — ❌; Microsoft 365 — ✅ Copilot.

Core differences summarized in three sentences:

OnlyOffice delivers "Microsoft format compatibility" — if your team primarily uses .docx and .xlsx, OnlyOffice's round-trip fidelity is best among open-source options.

Collabora delivers "lightweight + ODF ecosystem" — if your users mainly use ODF, Collabora's idle memory is only ~1GB.

Microsoft 365 delivers "native experience" — if private deployment is not required, Microsoft's cloud remains the most hassle-free choice.

7. Pros and Cons

Pros

Strongest Microsoft format compatibility — custom OOXML engine provides best round-trip fidelity for .docx, .xlsx, .pptx among open-source solutions. UI and interaction closely resemble Microsoft Office, lowering migration cost.

Lightweight mode deployment is extremely simple — since 9.4, community edition enforces lightweight mode: single-process architecture, one-command docker run. Friendly to 2C4G small machines and NAS environments.

Native online collaboration — real-time multi-user co-editing, version history, comments, track changes. Supports Fast and Strict collaboration modes.

Security features built-in — JWT dual verification, HTTPS enforcement, callback anti-forgery, field masking. No extra paid security modules needed.

Rich ecosystem — 40+ connectors and 50+ plugins; integrates with Nextcloud, ownCloud, Seafile, Odoo, Moodle; compatible with Office 365 and SharePoint.

Official community edition is free — AGPL v3 license, full core editing features. 9.4 removed the 20 concurrent connection limit.

Cons

Higher resource usage than Collabora — idle memory ~2GB vs Collabora's ~1GB. On VPS with <2GB RAM, OnlyOffice may not start.

Average compatibility with non-OOXML formats — OnlyOffice optimizes for OOXML. Heavy ODF or legacy .doc workloads may fare better with Collabora.

document.key mechanism is a common pitfall — many developers mistake document.key for file ID, causing session confusion, version conflicts, and apparent "content loss." Understanding this mechanism takes time.

Community edition lacks clustering — lightweight mode suits only single-machine small-scale deployments. High availability and horizontal scaling require the enterprise edition.

8. Suitable Scenarios

Enterprise OA system integration — ✅✅✅ Strongly recommended. Custom OOXML engine, best format compatibility.

Private document collaboration — ✅✅✅ Strongly recommended. Docker one-click deploy, full data control.

Nextcloud/ownCloud integration — ✅✅✅ Strongly recommended. Official connectors mature, simple deployment.

Teams primarily using Microsoft formats — ✅✅✅ Strongly recommended. Best round-trip fidelity in open-source.

SMEs/small teams — ✅✅✅ Strongly recommended. Lightweight mode friendly to 2C4G machines.

Need AI assistant — ✅✅ Recommended. Built-in AI assistant supports DeepSeek and other models.

Ultra-large-scale cluster deployment — ⚠️ Evaluate. Community edition lacks clustering; enterprise edition required.

Pure ODF format scenarios — ⚠️ Evaluate. Collabora may be more suitable.

9. Conclusion

Back to the original question: Why are more people using OnlyOffice?

The answer is straightforward — it turns "online document editing" from "buying licenses" into "self-hosted deployment."

Commercial document SDKs charge per year, per concurrent user, and require flagship upgrades for multi-user collaboration. OnlyOffice open-sources the core editing capability; you run it with Docker, data stays on your server, no third-party involvement.

Even more critical: version 9.4 slashes deployment complexity. Previously, deploying OnlyOffice meant configuring PostgreSQL, RabbitMQ, multiple Node processes — many gave up at environment setup. Now lightweight mode's single-process architecture starts with docker run -e MEMORY_MODE=true.

The document.key mechanism is the biggest pitfall, and also the biggest value. It takes time to grasp, but once understood, you see how it elegantly handles collaborative editing, version management, and cache reuse.

Of course, OnlyOffice is no silver bullet. Higher resource usage than Collabora, no clustering in community edition, average non-OOXML compatibility. But for enterprise OA integration, private document collaboration, and Microsoft-format-centric teams, it is already a very mature option.

10. Reference Resources

OnlyOffice official site: https://www.onlyoffice.com

DocumentServer GitHub: https://github.com/ONLYOFFICE/DocumentServer

API documentation: https://api.onlyoffice.com

Docker image:

onlyoffice/documentserver:9.4.0