Od
Applications Azure

ONLYOFFICE Docs on Ubuntu 24.04 on Azure User Guide

| Product: ONLYOFFICE Docs on Ubuntu 24.04 LTS on Azure

Overview

This guide covers the deployment and configuration of ONLYOFFICE Docs on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. ONLYOFFICE Docs (also known as Document Server) is an open source online office suite that provides full featured word processor, spreadsheet and presentation editors in the browser, together with a document editing and conversion API that other applications embed. It renders and co edits the common office formats with high fidelity and integrates with sync and share and document management platforms such as Nextcloud, ownCloud, Seafile, Confluence and Redmine, as well as your own applications through a documented JavaScript API.

The cloudimg image ships the free and open source, AGPL-3.0 licensed ONLYOFFICE Docs, installed unmodified from the official ONLYOFFICE Debian package, which brings its full runtime stack (PostgreSQL, RabbitMQ, Redis and nginx) the officially supported way. ONLYOFFICE secures its editing API with a JSON Web Token (JWT). Because a token secret that shipped inside the image would be identical on every VM, the cloudimg image generates a unique JWT secret for each VM on first boot, before the document services accept traffic, and writes it to a root only file. The document services are held behind a first boot gate until that per instance secret is in place, so the API never serves with a build time key, and every unsigned or wrong key request is rejected. Backed by 24/7 cloudimg support.

ONLYOFFICE is a trademark of Ascensio System SIA. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by ONLYOFFICE or Ascensio System SIA. It ships the free and open source AGPL-3.0 licensed self hosted software, unmodified.

The onlyoffice-firstboot, ds-docservice, ds-converter, nginx, postgresql, redis-server and rabbitmq-server services all reporting active, and the ONLYOFFICE healthcheck endpoint returning true

What is included:

  • ONLYOFFICE Docs (Document Server) v9.4.0, the AGPL-3.0 licensed community edition, installed from the official ONLYOFFICE apt repository
  • The full supporting stack installed the officially supported way: PostgreSQL, RabbitMQ, Redis and nginx as the front door on port 80
  • The document services (ds-docservice, ds-converter) plus nginx, postgresql, redis-server and rabbitmq-server as systemd units, enabled on boot
  • The built in editor test page at /example/, so you can create a document and confirm the editors render before integrating
  • A unique JWT token secret generated per VM on first boot, written 0600 root:root to /root/onlyoffice-credentials.txt, never baked into the image
  • A first boot gate that holds the document services back until the per instance secret is in place, so the API never serves with a build time key
  • No shipped secret: the editing API rejects every unsigned or wrong key request
  • Ubuntu 24.04 LTS base with latest security patches applied at build time
  • Azure Linux Agent for seamless cloud integration and SSH key injection
  • 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

  • Active Azure subscription, SSH public key, VNet + subnet in target region
  • Subscription to the ONLYOFFICE Docs listing on Azure Marketplace

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) is a sensible starting point for evaluation and light use. For teams doing real time co editing or heavy conversion use Standard_D2s_v5 or larger. NSG inbound: allow 22/tcp from your management network and 80/tcp for the document server from the host applications and browsers that use it.

Deploy from the Azure Marketplace

  1. Open the ONLYOFFICE Docs on Ubuntu 24.04 by cloudimg listing and select Get It Now, then Create.
  2. Choose your subscription, resource group and region, and a VM size (see above).
  3. Provide an SSH public key for the azureuser administrative account.
  4. On the Networking tab, attach the VM to your VNet and subnet and set the NSG inbound rules described above.
  5. Review and create. When the deployment completes, note the VM's public IP address.

Deploy from the Azure CLI

Create the VM, then open the ports the document server needs (SSH for administration, HTTP for the service):

az vm create \
  --resource-group my-rg \
  --name onlyoffice-docs \
  --image <this-marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group my-rg --name onlyoffice-docs --port 22 --priority 1001
az vm open-port --resource-group my-rg --name onlyoffice-docs --port 80 --priority 1002

First boot: the per instance JWT secret

On the first boot of each VM, a first boot service generates a unique JWT token secret, writes it into the document server configuration and into the built in example, creates a bootstrap ready marker that releases the document services, then records the secret in a root only credentials file. Nothing is baked into the image and no two VMs share a secret.

SSH in as azureuser and confirm the whole stack is active and the service is healthy:

systemctl is-active onlyoffice-firstboot ds-docservice ds-converter nginx postgresql redis-server rabbitmq-server
curl -s http://127.0.0.1/healthcheck

The health check prints true once the document server is ready.

Read the per instance credentials file to see your VM's JWT secret and the service URLs (the file is 0600 root:root, so use sudo):

sudo cat /root/onlyoffice-credentials.txt

The onlyoffice-credentials.txt file at mode 0600 root root, showing the per VM JWT secret masked, the welcome, example and health check URLs and the public IP, with a note that the secret is unique to this VM

The welcome page

Browse to http://<vm-ip>/ and you are redirected to the welcome page, which confirms the document server is installed and running and links to the integration options.

The ONLYOFFICE Docs welcome page confirming the Community Edition is installed and running, with integration options and a note that JWT is enabled by default

Try the editors: the built in test page

The image enables the bundled test page at http://<vm-ip>/example/. Use it to create a new document, spreadsheet or presentation, or upload a file, and confirm the editors open and render before you integrate the API into your own app.

The ONLYOFFICE Docs example page with a Create new panel offering Document, Spreadsheet, Presentation and PDF form, an upload control, and a list of sample documents ready to open

Select Document to open the word processor with a sample file. The editor loads with its full ribbon and the document renders in the page.

The ONLYOFFICE word processor open on a sample document titled Text Editors, showing formatted headings, body text, a bulleted list and WordArt rendered in the editing canvas with the full editing ribbon

Select Spreadsheet to open the spreadsheet editor. A sample workbook renders with its data, charts and filtered tables intact.

The ONLYOFFICE spreadsheet editor open on a Sales Report workbook, showing a formatted header, a revenue by industry bar chart, a stacked column chart and a filtered client table, all rendered in the grid

The JWT security model

The editing API is secured with a JSON Web Token. Token validation is enabled for browser and for inbound and outbound requests, so a host application must sign its requests to the document server with your VM's JWT secret. You can see the token configuration and prove the model from the command line.

A request signed with the per instance secret is accepted and returns the server version, while an unsigned request is rejected with token error 6:

SECRET=$(sudo grep '^JWT_SECRET=' /root/onlyoffice-credentials.txt | cut -d= -f2-)
TOKEN=$(python3 -c 'import sys,hmac,hashlib,base64,json;s=sys.argv[1];b=lambda x:base64.urlsafe_b64encode(x).rstrip(b"=");h=b(json.dumps({"alg":"HS256","typ":"JWT"},separators=(",",":")).encode());p=b(json.dumps({"c":"version"},separators=(",",":")).encode());import hmac as H;sig=b(H.new(s.encode(),h+b"."+p,hashlib.sha256).digest());sys.stdout.write((h+b"."+p+b"."+sig).decode())' "$SECRET")
curl -s -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  -X POST http://127.0.0.1/coauthoring/CommandService.ashx \
  -d "{\"c\":\"version\",\"token\":\"$TOKEN\"}"
echo
curl -s -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1/coauthoring/CommandService.ashx \
  -d '{"c":"version"}'

The signed call returns {"error":0,"version":"9.4.0.129"} and the unsigned call returns {"error":6}.

The document server JWT token validation enabled for browser, inbox and outbox, a JWT signed CommandService request returning error 0 and the server version, and an unsigned request rejected with error 6

A bundled helper runs the full check in one step: the welcome page and health check return 200, a signed request is accepted, and both an unsigned and a wrong secret request are rejected.

sudo /usr/local/sbin/onlyoffice-roundtrip.sh

The bundled round trip helper reporting OK: the welcome page and health check are up, a JWT signed CommandService request is accepted with error 0, and unsigned and wrong secret requests are rejected with error 6

Integrate with your application

Point your host application (for example Nextcloud, ownCloud or your own software) at http://<vm-ip>/ as the Document Server address, and configure it with the JWT secret from /root/onlyoffice-credentials.txt. The host application signs the editor configuration and API requests with that secret, and the document server validates every request. For public deployments, place the document server behind TLS (for example a reverse proxy or an Azure Application Gateway) so the token and document traffic are encrypted in transit.

To rotate the secret later, update services.CoAuthoring.secret.* in /etc/onlyoffice/documentserver/local.json, restart the document services, and update the same secret in your host application.

Support

Every cloudimg image includes 24/7 support with a guaranteed 24 hour response SLA. Contact support through the cloudimg website for deployment help, integration questions or issues with this image.