Why OnlyOffice 9.4's Lightweight Mode Is Winning Developers: Architecture, Integration & Deployment Guide

What Is OnlyOffice?

OnlyOffice is not a full office suite or cloud drive — it is a document editing backend service (DocumentServer) that runs on your server. Users edit documents in the browser; files stay on your infrastructure, never touching third parties. Unlike LibreOffice (desktop) and its online variant Collabora Online, OnlyOffice uses a custom OOXML engine built for .docx/.xlsx/.pptx fidelity.

Architecture Overview

The system splits responsibilities: your application provides the document manager and storage (e.g., OnlyOffice DocSpace or a custom implementation), while DocumentServer handles editing, conversion, command, and build services. An architecture diagram illustrates this separation.

Core Principle: document.key and Editing Lifecycle

document.key is the unique identifier of the current collaborative editing version , not the file ID. It determines five behaviors: whether users join the same co-editing session, whether the cached Editor.bin is reused, whether the file is considered changed, whether the original file is re-downloaded, and whether users share the same editing version.

The editing lifecycle:

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

Co-editing → multiple users with same key0 edit the same Editor.bin cache; original file unchanged.

Save trigger → only when all users exit or force-save does OnlyOffice generate output.docx and send callback with status = 2 or 6.

Why "content loss" happens: many systems ignore the callback and keep the old original file. Next open downloads the stale file — the new output.docx was never saved.

Java Integration with Spring Boot

4.1 Deploy DocumentServer (Lightweight Mode)

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

Verify at http://localhost:8080.

4.2 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);
        Map<String, Object> config = Map.of(
            "document", Map.of(
                "fileType", doc.getExtension(),
                "key", doc.getVersionKey(), // critical: change on content change
                "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 reuses the stale Editor.bin cache.

4.3 Handle Save Callback

@PostMapping("/callback")
@ResponseBody
public String handleCallback(@RequestBody Map<String, Object> data) {
    // status 2 or 6 = document ready to save
    if ("2".equals(data.get("status")) || "6".equals(data.get("status"))) {
        String downloadUrl = (String) ((Map) data.get("url")).get("url");
        saveDocument(downloadUrl, (String) data.get("key"));
        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>

Lightweight Mode (9.4.0+)

Version 9.4.0 makes lightweight mode mandatory for Community Edition , replacing the traditional distributed architecture (Nginx + PostgreSQL + RabbitMQ + multiple Node processes) with a single-process monolithic architecture . Deployment shifts from docker-compose multi-container orchestration to a single docker run command.

Comparison: Standard Mode vs Lightweight Mode

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

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

Resource Usage: Standard — High (MQ + DB resident); Lightweight — Low

Ops Complexity: Standard — High; Lightweight — Low

Best For: Standard — High-concurrency large clusters; Lightweight — SMEs, small teams, POC, NAS, ARM low-spec, offline

Enable with -e MEMORY_MODE=true. State becomes in-memory; no external DB or MQ needed. For cluster/high-availability needs, stick with Enterprise Edition standard mode.

Comparison: OnlyOffice vs Collabora Online vs Microsoft 365

Core Engine

OnlyOffice: Custom OOXML engine

Collabora Online: LibreOffice core

Microsoft 365: Microsoft native

Native Format

OnlyOffice: OOXML (.docx/.xlsx/.pptx)

Collabora Online: ODF

Microsoft 365: OOXML

MS Format Compatibility

OnlyOffice: Strongest

Collabora Online: Average

Microsoft 365: Native

Deployment

OnlyOffice: Docker/Linux/Windows

Collabora Online: Docker/Linux

Microsoft 365: Cloud only

Private Deployment

OnlyOffice: ✅

Collabora Online: ✅

Microsoft 365: ❌

Idle Memory

OnlyOffice: ~2 GB

Collabora Online: ~1 GB

Microsoft 365: N/A

Free Tier Limits

OnlyOffice: 20 concurrent connections (removed in 9.4)

Collabora Online: 20 docs / 10 connections

Microsoft 365: No free tier

Co-editing

OnlyOffice: ✅ Real-time

Collabora Online: ✅ Real-time

Microsoft 365: ✅

AI Assistant

OnlyOffice: ✅ Built-in (DeepSeek, etc.)

Collabora Online: ❌

Microsoft 365: ✅ Copilot

Three-sentence summary: OnlyOffice delivers Microsoft-format compatibility ; Collabora offers lightweight + ODF ecosystem ; Microsoft 365 gives native cloud experience .

Pros & Cons

Pros

Best MS-format fidelity — custom OOXML engine, UI/UX close to Office, low migration cost.

Ultra-simple deployment — 9.4 lightweight mode, single process, docker run on 2C4G machines.

Native real-time collaboration — Fast/Strict modes, version history, comments, track changes.

Security built-in — JWT dual verification, HTTPS enforcement, callback anti-forgery, field masking; no extra paid modules.

Rich ecosystem — 40+ connectors, 50+ plugins for Nextcloud, ownCloud, Seafile, Odoo, Moodle, Office 365, SharePoint.

Free Community Edition (AGPL v3) — full core editing; 9.4 drops the 20-connection limit.

Cons

Higher memory than Collabora — ~2 GB idle vs ~1 GB; may not run on <2 GB VPS.

Weaker non-OOXML support — ODF or legacy .doc files may render better in Collabora.

document.key pitfalls — developers often mistake it for file ID, causing session conflicts, version clashes, apparent "data loss". Learning curve required.

Community Edition lacks clustering — lightweight mode is single-node only; HA/scale-out needs Enterprise Edition.

Recommended Use Cases

Enterprise OA integration — ✅✅✅ Strongly recommended. Reason: Custom OOXML engine, best format fidelity.

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

Nextcloud/ownCloud integration — ✅✅✅ Strongly recommended. Reason: Mature official connectors, easy deploy.

Teams using mainly MS formats — ✅✅✅ Strongly recommended. Reason: Round-trip fidelity best in open source.

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

Need AI assistant — ✅✅ Recommended. Reason: Built-in AI, supports DeepSeek etc.

Massive cluster deployment — ⚠️ Evaluate. Reason: Community lacks clustering; need Enterprise.

Pure ODF environments — ⚠️ Evaluate. Reason: Collabora may fit better.

Conclusion

OnlyOffice turns "online document editing" from a licensed-service purchase into a self-hosted capability. Commercial SDKs charge per year/per seat/per concurrent user; OnlyOffice open-sources the core editor — run it with Docker, keep data on your servers, no third-party transit. Version 9.4 slashes deployment complexity: previously you managed PostgreSQL, RabbitMQ, multiple Node processes; now docker run -e MEMORY_MODE=true starts everything in one process.

The document.key mechanism is the biggest pitfall and the greatest value. It takes time to grasp, but once understood, it makes collaborative editing, versioning, and cache reuse elegant.

OnlyOffice isn't a silver bullet — higher RAM than Collabora, no clustering in Community, weaker non-OOXML support — but for OA integration, private collaboration, and MS-format-centric teams, it's a mature, production-ready choice.

References

OnlyOffice Official : https://www.onlyoffice.com

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

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

Docker Image :

onlyoffice/documentserver:9.4.0