ONLYOFFICE DocSpace on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of ONLYOFFICE DocSpace on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. ONLYOFFICE DocSpace is an open source, room based document collaboration platform. Work is organised into rooms: collaboration rooms for co editing, public rooms that publish content through links, form filling rooms that collect responses, custom rooms that combine the rules you need, and virtual data rooms with watermarks, file lifetimes and download controls. Every room opens files in the ONLYOFFICE Docs editors, so word processing, spreadsheets, presentations, forms and PDF work happen in the browser with real time co editing, comments, track changes and version history.

DocSpace is a stack of more than twenty services rather than one program: a set of .NET and Node.js backends, two Java identity services, MySQL as the database, Redis as the cache, RabbitMQ as the event bus, OpenSearch for full text search, OpenResty as the application router, and a separate ONLYOFFICE Docs 9.4 Document Server that renders the editors. The cloudimg image installs all of it from ONLYOFFICE's official native packages, pinned to exact versions, and wires it the way the vendor's own installer does, minus the parts that would compromise the image: no swap file, no relicensed Redis build, no logging dashboards that phone home.

Nothing in this image ships with a known secret, and nobody can claim your portal before you do. The MySQL, RabbitMQ and Redis passwords, the Document Server JWT secret, DocSpace's signing key, the identity encryption secret and the TLS certificate are all generated on the first boot of every VM. DocSpace's first run wizard, which creates the owner account, is held behind a one time setup link that exists only in a root readable file on your VM; the front door answers 403 to everyone else until you have completed the wizard, then unlocks itself and DocSpace's own sign in takes over. 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, sponsored by, or endorsed by Ascensio System SIA. It ships the free and open source ONLYOFFICE DocSpace Community and ONLYOFFICE Docs Community software unmodified under the GNU AGPL v3; corresponding sources are at https://github.com/ONLYOFFICE/DocSpace and https://github.com/ONLYOFFICE/DocumentServer. No ONLYOFFICE logo is used on this page.

What is included:

• ONLYOFFICE DocSpace Community 3.7.2 — installed from the official ONLYOFFICE apt repository as the docspace package set, every component pinned to 3.7.2.577
• ONLYOFFICE Docs Community 9.4.0 — the Document Server that renders the editors, bound to loopback and reached through DocSpace. As of 9.4.0 upstream removed the Community edition's historic limit of 20 simultaneously opened documents; this image ships that build unmodified
• MySQL 8.0, Redis 7.0 and RabbitMQ from the Ubuntu archive, OpenSearch 2.19.6 and OpenResty from their vendors, .NET 10, Node.js 22 and OpenJDK 21 runtimes
• A TLS front door — OpenResty terminates HTTPS on port 443 with a certificate generated for this VM's address, and redirects port 80
• A first time setup gate — the owner creating wizard is reachable only through a one time per VM link
• First boot secret generation — database, broker and cache passwords, the Document Server JWT secret, the signing key, the identity encryption secret and the TLS certificate, all unique to each VM
• Everything else on loopback — only TCP 22, 80 and 443 are reachable from outside, enforced both by binding and by a default deny host firewall

Prerequisites

• An Azure subscription with permission to create virtual machines
• An SSH key pair for VM access
• A VM size of Standard_B4ms or larger (4 vCPU, 16 GiB RAM). Measured at idle, the DocSpace services use about 4.8 GB, OpenSearch 4.6 GB, the identity services 1.4 GB and MySQL 0.6 GB. ONLYOFFICE's own installer requires 8 GB and adds a swap file below 12 GB; this image deliberately ships no swap, so a 16 GiB size is the honest minimum
• Inbound network security group rules for TCP 22 and 443 (and 80 if you want the redirect)
• Optionally, a DNS name you control, if you want a trusted certificate

Step 1: Deploy from the Azure Portal

1. In the Azure Portal, search the Marketplace for ONLYOFFICE DocSpace on Ubuntu 24.04 LTS and select the cloudimg offer.
2. Choose Standard_B4ms or larger.
3. Set the administrator username to azureuser and upload your SSH public key.
4. On the Networking tab, allow inbound SSH (22) and HTTPS (443).
5. Review and create.

Step 2: Deploy from the Azure CLI

az vm create \
  --resource-group my-docspace-rg \
  --name my-docspace-vm \
  --image cloudimg:onlyoffice-docspace-ubuntu-24-04:default:latest \
  --size Standard_B4ms \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Step 3: Connect to your VM

ssh azureuser@<vm-ip>

Step 4: Wait for first boot and confirm the services are running

onlyoffice-docspace-firstboot is a one shot unit that runs once, on the very first boot. It generates every secret this VM needs, issues the TLS certificate, arms the setup gate, and only then releases the DocSpace and Document Server services. Until it has finished, the web address answers HTTP 503 rather than serving anything half configured.

sudo systemctl status onlyoffice-docspace-firstboot.service --no-pager | head -5

The stack then takes two to three minutes to warm up on a fresh boot, because more than twenty services compile and start at once. Confirm the core of it is active:

systemctl is-active mysql redis-server rabbitmq-server opensearch openresty nginx ds-docservice \
  docspace-api docspace-studio docspace-files docspace-people-server docspace-login docspace-doceditor \
  docspace-socket docspace-identity-api docspace-identity-authorization | sort | uniq -c

Expected output:

     16 active

Confirm the DocSpace API is answering through the loopback front:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/2.0/settings

Expected output:

200

And that the Document Server behind it is healthy:

curl -s http://127.0.0.1/ds-vpath/healthcheck; echo

Expected output:

true

Step 5: Retrieve your per instance credentials and the setup link

Everything unique to this VM is written to a root only file on first boot:

sudo cat /root/onlyoffice-docspace-credentials.txt

This file contains:

• DOCSPACE_URL — the address to open in a browser, https://<your VM address>/
• SETUP_URL — the one time setup link that unlocks the first run wizard, and SETUP_KEY, the key inside it
• MYSQL_PASSWORD, RABBITMQ_PASSWORD, REDIS_PASSWORD — the per VM passwords of the onlyoffice database, broker and cache accounts, all on loopback
• JWT_SECRET — the secret that authenticates every request between DocSpace and the Document Server

Step 6: Understand the setup gate

DocSpace creates its owner account through a wizard that upstream serves to anyone who reaches the portal first. On a public IP that is a race you could lose. This image closes it: until the wizard has been completed, every request to the front door is answered with 403 unless it carries a cookie that only the setup link can set.

sudo onlyoffice-docspace-setup-gate status

Expected output on a freshly deployed VM:

armed (waiting for the owner to complete the setup wizard)

Prove it from the VM itself. Without the cookie the portal is closed:

curl -ks -o /dev/null -w '%{http_code}\n' https://127.0.0.1/

Expected output:

403

A wrong key is refused just the same, while the real setup link answers with a redirect and sets the cookie:

SETUP_KEY=$(sudo grep '^SETUP_KEY=' /root/onlyoffice-docspace-credentials.txt | cut -d= -f2-)
WRONG=$(curl -ks -o /dev/null -w '%{http_code}' 'https://127.0.0.1/cloudimg-setup?key=not-the-key')
RIGHT=$(curl -ks -o /dev/null -w '%{http_code}' "https://127.0.0.1/cloudimg-setup?key=${SETUP_KEY}")
echo "wrong key -> ${WRONG}; setup link -> ${RIGHT}"

Expected output:

wrong key -> 403; setup link -> 302

A timer on the VM polls DocSpace every ten seconds and opens the gate the moment the wizard reports complete. If you ever need to open it by hand, sudo onlyoffice-docspace-setup-gate lift does so immediately.

Step 7: Create the owner account

Open the SETUP_URL from Step 5 in a browser. The image ships a self signed certificate generated for this VM, so your browser will warn on the first visit; accept it, or install a trusted certificate as described below. The link sets the setup cookie and takes you straight to the DocSpace wizard, where you choose the owner e mail address and password.

Within seconds of the wizard finishing, the gate opens and the same address serves DocSpace's own sign in page to everyone. From here on the portal is protected by DocSpace's accounts, roles and sharing rules exactly as upstream designed them.

Step 8: Create a room and edit a document

Sign in as the owner and use Rooms to create your first room. A collaboration room is the right choice for a team that co edits files together. Inside the room, Create new starts a document, spreadsheet, presentation or form, and Upload brings in existing files.

Opening the document launches the ONLYOFFICE Docs editor in the same tab. The editor is served by the Document Server on this VM, reached through the front door under /ds-vpath/, and every editing session is authenticated with the per VM JWT secret from Step 5. Text you type is saved back into the room automatically.

Step 9: Invite people

Contacts is where members, guests and admins live. Invite by e mail once you have configured an SMTP server under Settings → Integration → SMTP settings, or generate an invitation link and hand it out yourself, which needs no mail server at all.

Step 10: Understand the security model

List every socket bound to something other than loopback, so anything unexpected has nowhere to hide:

sudo ss -lntH | awk '{print $4}' | grep -vE '^(127\.|\[::1\]|\[::ffff:127\.)' | sed -E 's/.*:([0-9]+)$/\1/' | sort -un | tr '\n' ' '; echo

Expected output:

22 80 443 8000 

Ports 22, 80 and 443 are the public surface. Port 8000 is the Document Server's internal process: it is a compiled binary that binds every interface and offers no setting to change that, so the image closes it with a host firewall instead. ufw runs with a default deny inbound policy and exactly three allow rules:

sudo ufw status verbose | grep -E '^(Status|Default)|ALLOW IN'

Expected output:

Status: active
Default: deny (incoming), allow (outgoing), disabled (routed)
22/tcp                     ALLOW IN    Anywhere
80/tcp                     ALLOW IN    Anywhere
443/tcp                    ALLOW IN    Anywhere
22/tcp (v6)                ALLOW IN    Anywhere (v6)
80/tcp (v6)                ALLOW IN    Anywhere (v6)
443/tcp (v6)               ALLOW IN    Anywhere (v6)

Every backend sits on loopback: MySQL on 3306, Redis on 6379, RabbitMQ on 5672, OpenSearch on 9200, the Document Server's nginx on 8083, the DocSpace router on 8092 and the individual DocSpace services on 5000 to 5158, 8080, 8888, 9090, 9834, 9899 and 9999:

sudo ss -lntH | awk '{print $4}' | grep -E ':(3306|6379|5672|9200|8083|8092|5011|9899|9090)$' | sort -u

Expected output:

127.0.0.1:3306
127.0.0.1:5011
127.0.0.1:5672
127.0.0.1:6379
127.0.0.1:8083
127.0.0.1:8092
127.0.0.1:9899
[::1]:9200
[::ffff:127.0.0.1]:9090
[::ffff:127.0.0.1]:9200

The passwords in the credentials file are the live ones, and none of the backends answers without them:

MYSQL_PASSWORD=$(sudo grep '^MYSQL_PASSWORD=' /root/onlyoffice-docspace-credentials.txt | cut -d= -f2-)
REDIS_PASSWORD=$(sudo grep '^REDIS_PASSWORD=' /root/onlyoffice-docspace-credentials.txt | cut -d= -f2-)
mysql -uonlyoffice -p"${MYSQL_PASSWORD}" -N -e 'SELECT COUNT(*) AS tables_in_onlyoffice FROM information_schema.tables WHERE table_schema="onlyoffice"' 2>/dev/null
redis-cli -a "${REDIS_PASSWORD}" --no-auth-warning ping
redis-cli ping 2>&1 | grep -o NOAUTH

Expected output (the table count grows with upgrades):

86
PONG
NOAUTH

The Document Server only accepts editing sessions signed with this VM's JWT secret, and DocSpace signs every one with the same value:

JWT=$(sudo grep '^JWT_SECRET=' /root/onlyoffice-docspace-credentials.txt | cut -d= -f2-)
DS=$(sudo jq -r '.services.CoAuthoring.secret.inbox.string' /etc/onlyoffice/documentserver/local.json)
APP=$(sudo jq -r '.files.docservice.secret.value' /etc/onlyoffice/docspace/appsettings.community.json)
[ "${JWT}" = "${DS}" ] && [ "${JWT}" = "${APP}" ] && echo "DocSpace and Document Server share this VM's JWT secret" || echo "MISMATCH"

Expected output:

DocSpace and Document Server share this VM's JWT secret

Using your own domain and a trusted certificate

Point an A record at the VM's public IP, open port 80 in your network security group for the certificate challenge, then let ONLYOFFICE's own tool obtain a Let's Encrypt certificate. It rewrites the OpenResty front door in the same layout this image uses and sets DocSpace's portal address to your domain:

sudo docspace-ssl-setup you@example.com docspace.your-domain.example

For a certificate you already hold, use the file form instead:

sudo docspace-ssl-setup --file docspace.your-domain.example /path/to/fullchain.pem /path/to/privkey.pem

Both forms replace the cloudimg front door configuration with upstream's; the setup gate is no longer needed once the owner exists, so nothing is lost. The per VM self signed certificate lives at /etc/cloudimg/onlyoffice-docspace/tls/ if you ever want to return to it.

Updating DocSpace

The ONLYOFFICE, OpenSearch, OpenResty and Node.js repositories stay configured, so DocSpace and the Document Server update with apt. Operating system security updates are applied automatically by unattended-upgrades.

sudo apt-get update
sudo apt-get install --only-upgrade docspace onlyoffice-documentserver

If an upgrade re runs docspace-configuration, it restores ONLYOFFICE's plain HTTP proxy layout. Put the TLS front door back with:

sudo cp /etc/cloudimg/onlyoffice-docspace/onlyoffice-proxy.conf.cloudimg /etc/openresty/conf.d/onlyoffice-proxy.conf
sudo systemctl restart openresty

Upgrading OpenSearch

OpenSearch needs one extra step, because its Debian package ships opensearch.yml and jvm.options as ordinary files rather than as configuration files that dpkg protects. An apt upgrade therefore overwrites both, puts the bundled security plugin back, and leaves the ingest-attachment plugin built for the previous version, so the node either refuses DocSpace's plain HTTP client or does not start at all. Re apply ONLYOFFICE's own OpenSearch settings after any OpenSearch upgrade, exactly as docspace-configuration does:

sudo systemctl stop opensearch
sudo sed -i '/^plugins\.security\./,/^[^ ]/d' /etc/opensearch/opensearch.yml
sudo /usr/share/opensearch/bin/opensearch-plugin remove opensearch-security
sudo /usr/share/opensearch/bin/opensearch-plugin remove ingest-attachment
sudo /usr/share/opensearch/bin/opensearch-plugin install -b ingest-attachment
sudo systemctl start opensearch

Confirm it came back with curl -s http://127.0.0.1:9200/ | head, which should print the node's name and the OpenSearch version.

Backups

DocSpace has its own backup and restore under Settings → Backup, which packages the database and the file store together and can copy them to Azure Blob Storage or another S3 compatible target. From the shell, back up the same two things:

MYSQL_PASSWORD=$(sudo grep '^MYSQL_PASSWORD=' /root/onlyoffice-docspace-credentials.txt | cut -d= -f2-)
mysqldump -uonlyoffice -p"${MYSQL_PASSWORD}" --single-transaction onlyoffice | gzip > /var/backups/docspace-$(date +%F).sql.gz
sudo tar czf /var/backups/docspace-data-$(date +%F).tar.gz -C /var/www/onlyoffice Data

Server components

Component	Version	Listens on	Purpose
ONLYOFFICE DocSpace Community	3.7.2.577	127.0.0.1:5000 to 5158, 8080, 8888, 9090, 9834, 9899, 9999	Rooms, files, people, login, editor host, sockets, identity, backup, notifications
ONLYOFFICE Docs Community	9.4.0	127.0.0.1:8083 (nginx), 8000 (firewalled)	Document, spreadsheet, presentation, form and PDF editors
OpenResty	1.31.1.1	0.0.0.0:80, 0.0.0.0:443, 127.0.0.1:8092	TLS front door, setup gate, application router
MySQL	8.0	127.0.0.1:3306	DocSpace database
Redis	7.0.15	127.0.0.1:6379	Cache and sessions, password protected
RabbitMQ	3.12	127.0.0.1:5672	Event bus between the DocSpace services
OpenSearch	2.19.6	127.0.0.1:9200	Full text search index
ufw			Default deny inbound; allows 22, 80 and 443 only

Key files and directories

Path	Purpose
/root/onlyoffice-docspace-credentials.txt	Per VM credentials and the one time setup link, 0600 root
/etc/onlyoffice/docspace/	DocSpace configuration (appsettings.community.json, systemd.env, redis.community.json, rabbitmq.community.json)
/etc/onlyoffice/documentserver/local.json	Document Server configuration, including the JWT secret
/etc/openresty/conf.d/onlyoffice-proxy.conf	The TLS front door and setup gate
/etc/cloudimg/onlyoffice-docspace/	Per VM TLS keypair, the armed setup key, and a copy of the front door configuration
/var/www/onlyoffice/Data/	Uploaded documents and room content
/var/log/onlyoffice/docspace/	Per service DocSpace logs
/var/log/onlyoffice/documentserver/	Document Server logs
/var/log/nginx/access-proxy.log	Front door access log

Troubleshooting

The address answers 503. First boot has not finished. Watch sudo journalctl -u onlyoffice-docspace-firstboot -f and give the services two to three minutes after it completes.

The address answers 403. The setup gate is armed and you have not used the setup link. Open the SETUP_URL from /root/onlyoffice-docspace-credentials.txt, or if the wizard was completed by other means, run sudo onlyoffice-docspace-setup-gate lift.

A page or the editor shows 502. A backend is still starting; systemctl list-units 'docspace-*' --state=activating shows which. The identity services are the slowest to come up.

A document will not open. Check curl -s http://127.0.0.1/ds-vpath/healthcheck returns true, then sudo journalctl -u ds-docservice -n 50. A JWT mismatch shows in the Document Server log as a token error; the check in Step 10 confirms both sides share the secret.

I re ran docspace-configuration and lost HTTPS. Restore the front door as described under "Updating DocSpace".

Support

This image is published and supported by cloudimg with 24/7 support. Contact support@cloudimg.co.uk with your Azure subscription ID and the VM name.