OpenCloud + OnlyOffice — Bare-Metal Deployment Guide

Domain: opencloud.local (private/local network with self-signed TLS) Stack: OpenCloud binary + Nginx + OnlyOffice Document Server — no Docker required Latest tested version: OpenCloud v7.2.0

Architecture

Internet / LAN (ports 80 & 443)
         │
       Nginx  ← self-signed TLS certificate
         │
         ├── cloud.opencloud.local         → OpenCloud binary        (127.0.0.1:9200)
         ├── wopiserver.opencloud.local     → Collaboration/WOPI svc  (127.0.0.1:9300)
         └── onlyoffice.opencloud.local     → OnlyOffice Doc Server   (127.0.0.1:8080)

All components run as systemd services.

Prerequisites

Ubuntu 22.04 LTS or Debian 12
Root or sudo access
Minimum hardware: 4 CPU cores, 8 GB RAM, 50 GB disk
Ports 80 and 443 open in your firewall

Hosts file setup
Create system user
Download OpenCloud binary
Create directories
Initialize OpenCloud
Create app-registry config
Create CSP config
Create environment file
Create systemd service
Install Nginx
Generate self-signed TLS certificate
Configure Nginx
Install OnlyOffice Document Server
Configure OnlyOffice port
Enable WOPI in OnlyOffice
Restart all services
Trust the self-signed certificate
Verify the deployment
Maintenance reference

1. Hosts file setup

Add the three local subdomains on every machine that will access the server. Replace 192.168.x.x with the actual IP address of your server.

echo "192.168.x.x  cloud.opencloud.local wopiserver.opencloud.local onlyoffice.opencloud.local" \
  | sudo tee -a /etc/hosts

2. Create system user

OpenCloud runs as a dedicated non-login system user for security.

sudo useradd --system --no-create-home --shell /sbin/nologin opencloud

3. Download OpenCloud binary

OC_VERSION="7.2.0"
ARCH="amd64"   # change to arm64 for ARM servers

sudo mkdir -p /opt/opencloud/bin

sudo curl -L -o /opt/opencloud/bin/opencloud \
  "https://github.com/opencloud-eu/opencloud/releases/download/v${OC_VERSION}/opencloud-${OC_VERSION}-linux-${ARCH}"

sudo chmod +x /opt/opencloud/bin/opencloud
sudo ln -s /opt/opencloud/bin/opencloud /usr/local/bin/opencloud

# Confirm it works
opencloud --version

4. Create directories

sudo mkdir -p /var/lib/opencloud /etc/opencloud
sudo chown -R opencloud:opencloud /var/lib/opencloud /etc/opencloud

5. Initialize OpenCloud

Run init once as the opencloud user to generate the config file with random JWT secrets. This command is safe to re-run — it will not overwrite an existing config.

sudo -u opencloud \
  OC_CONFIG_DIR=/etc/opencloud \
  opencloud init \
  --insecure no \
  --admin-password "YourStrongPassword123!"

The generated config is written to /etc/opencloud/opencloud.yaml. Change the admin password to something strong before running this.

6. Create app-registry config

This file tells OpenCloud which app to use for each file type. All office formats are routed to OnlyOffice.

sudo tee /etc/opencloud/app-registry.yaml > /dev/null << 'EOF'
app_registry:
  mimetypes:
  - mime_type: application/pdf
    extension: pdf
    name: PDF
    description: PDF document
    icon: ''
    default_app: ''
    allow_creation: false
  - mime_type: application/vnd.oasis.opendocument.text
    extension: odt
    name: OpenDocument
    description: OpenDocument text document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.oasis.opendocument.spreadsheet
    extension: ods
    name: OpenSpreadsheet
    description: OpenDocument spreadsheet document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.oasis.opendocument.presentation
    extension: odp
    name: OpenPresentation
    description: OpenDocument presentation document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
    extension: docx
    name: Microsoft Word
    description: Microsoft Word document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.wordprocessingml.form
    extension: docxf
    name: Form Document
    description: Form Document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
    extension: xlsx
    name: Microsoft Excel
    description: Microsoft Excel document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.presentationml.presentation
    extension: pptx
    name: Microsoft PowerPoint
    description: Microsoft PowerPoint document
    icon: ''
    default_app: OnlyOffice
    allow_creation: true
  - mime_type: application/vnd.jupyter
    extension: ipynb
    name: Jupyter Notebook
    description: Jupyter Notebook
    icon: ''
    default_app: ''
    allow_creation: true
EOF

sudo chown opencloud:opencloud /etc/opencloud/app-registry.yaml

7. Create CSP config

Content Security Policy — allows the browser to load OnlyOffice inside the OpenCloud web interface.

sudo tee /etc/opencloud/csp.yaml > /dev/null << 'EOF'
directives:
  child-src:
    - "'self'"
  connect-src:
    - "'self'"
    - "blob:"
  default-src:
    - "'none'"
  font-src:
    - "'self'"
  frame-ancestors:
    - "'self'"
  frame-src:
    - "'self'"
    - "blob:"
    - "https://onlyoffice.opencloud.local/"
  img-src:
    - "'self'"
    - "data:"
    - "blob:"
    - "https://onlyoffice.opencloud.local/"
  manifest-src:
    - "'self'"
  media-src:
    - "'self'"
  object-src:
    - "'self'"
    - "blob:"
  script-src:
    - "'self'"
    - "'unsafe-inline'"
  style-src:
    - "'self'"
    - "'unsafe-inline'"
EOF

sudo chown opencloud:opencloud /etc/opencloud/csp.yaml

8. Create environment file

All runtime configuration is kept in this file and loaded by the systemd unit.

sudo tee /etc/opencloud/opencloud.env > /dev/null << 'EOF'
# ── Paths ─────────────────────────────────────────────────
OC_CONFIG_DIR=/etc/opencloud
OC_BASE_DATA_PATH=/var/lib/opencloud

# ── Public URL ────────────────────────────────────────────
OC_URL=https://cloud.opencloud.local

# ── Security ──────────────────────────────────────────────
# OC_INSECURE=true allows self-signed certs to be accepted internally
OC_INSECURE=true
# PROXY_TLS=false because Nginx handles TLS termination
PROXY_TLS=false
PROXY_ENABLE_BASIC_AUTH=false

# ── Admin ─────────────────────────────────────────────────
IDM_ADMIN_PASSWORD=YourStrongPassword123!
IDM_CREATE_DEMO_USERS=false

# ── Logging ───────────────────────────────────────────────
OC_LOG_LEVEL=info
OC_LOG_PRETTY=false

# ── Internal NATS message bus ─────────────────────────────
NATS_NATS_HOST=127.0.0.1
NATS_NATS_PORT=9233
MICRO_REGISTRY_ADDRESS=127.0.0.1:9233

# ── Gateway (required by collaboration service) ───────────
GATEWAY_GRPC_ADDR=0.0.0.0:9142

# ── Optional services to start ────────────────────────────
# notifications: email alerts
# collaboration: WOPI bridge for OnlyOffice
OC_ADD_RUN_SERVICES=notifications,collaboration

# ── Collaboration / WOPI bridge ───────────────────────────
COLLABORATION_GRPC_ADDR=0.0.0.0:9301
COLLABORATION_HTTP_ADDR=0.0.0.0:9300
MICRO_REGISTRY=nats-js-kv
COLLABORATION_WOPI_SRC=https://wopiserver.opencloud.local
COLLABORATION_APP_NAME=OnlyOffice
COLLABORATION_APP_PRODUCT=OnlyOffice
COLLABORATION_APP_ADDR=https://onlyoffice.opencloud.local
COLLABORATION_APP_ICON=https://onlyoffice.opencloud.local/web-apps/apps/documenteditor/main/resources/img/favicon.ico
COLLABORATION_APP_INSECURE=true
COLLABORATION_CS3API_DATAGATEWAY_INSECURE=true

# ── Frontend: use OnlyOffice as the document editor ───────
FRONTEND_APP_HANDLER_SECURE_VIEW_APP_ADDR=eu.opencloud.api.collaboration.OnlyOffice

# ── Config file locations ─────────────────────────────────
PROXY_CSP_CONFIG_FILE_LOCATION=/etc/opencloud/csp.yaml

# ── SMTP notifications (optional) ────────────────────────
# Uncomment and fill in to enable email notifications
#NOTIFICATIONS_SMTP_HOST=smtp.opencloud.local
#NOTIFICATIONS_SMTP_PORT=587
NOTIFICATIONS_SMTP_SENDER=opencloud@opencloud.local
#NOTIFICATIONS_SMTP_USERNAME=
#NOTIFICATIONS_SMTP_PASSWORD=
#NOTIFICATIONS_SMTP_ENCRYPTION=starttls
EOF

sudo chmod 600 /etc/opencloud/opencloud.env
sudo chown opencloud:opencloud /etc/opencloud/opencloud.env

9. Create systemd service

sudo tee /etc/systemd/system/opencloud.service > /dev/null << 'EOF'
[Unit]
Description=OpenCloud Server
Documentation=https://docs.opencloud.eu
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=opencloud
Group=opencloud
EnvironmentFile=/etc/opencloud/opencloud.env
ExecStart=/opt/opencloud/bin/opencloud server
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=opencloud

# Hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable opencloud
sudo systemctl start opencloud

Confirm it started successfully:

sudo systemctl status opencloud
sudo journalctl -u opencloud -f --no-pager

Wait for a line like server started before proceeding.

10. Install Nginx

sudo apt update
sudo apt install -y nginx

11. Generate self-signed TLS certificate

A single certificate covers all three local subdomains via Subject Alternative Names.

sudo mkdir -p /etc/ssl/opencloud

sudo openssl req -x509 -nodes -days 3650 -newkey rsa:4096 \
  -keyout /etc/ssl/opencloud/opencloud.local.key \
  -out    /etc/ssl/opencloud/opencloud.local.crt \
  -subj   "/CN=opencloud.local/O=OpenCloud Local/C=US" \
  -addext "subjectAltName=DNS:cloud.opencloud.local,DNS:wopiserver.opencloud.local,DNS:onlyoffice.opencloud.local"

sudo chmod 600 /etc/ssl/opencloud/opencloud.local.key
sudo chmod 644 /etc/ssl/opencloud/opencloud.local.crt

12. Configure Nginx

sudo tee /etc/nginx/sites-available/opencloud.conf > /dev/null << 'EOF'
# ── Redirect HTTP → HTTPS ─────────────────────────────────
server {
    listen 80;
    server_name cloud.opencloud.local wopiserver.opencloud.local onlyoffice.opencloud.local;
    return 301 https://$host$request_uri;
}

# ── OpenCloud web interface ───────────────────────────────
server {
    listen 443 ssl;
    server_name cloud.opencloud.local;

    ssl_certificate     /etc/ssl/opencloud/opencloud.local.crt;
    ssl_certificate_key /etc/ssl/opencloud/opencloud.local.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Allow large file uploads
    client_max_body_size 10G;

    # Long timeouts for WebDAV clients
    proxy_read_timeout  43200s;
    proxy_send_timeout  43200s;

    location / {
        proxy_pass         http://127.0.0.1:9200;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_http_version 1.1;
        # WebSocket support (needed for real-time collaboration)
        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";
        proxy_buffering    off;
    }
}

# ── WOPI / Collaboration service ──────────────────────────
server {
    listen 443 ssl;
    server_name wopiserver.opencloud.local;

    ssl_certificate     /etc/ssl/opencloud/opencloud.local.crt;
    ssl_certificate_key /etc/ssl/opencloud/opencloud.local.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location / {
        proxy_pass         http://127.0.0.1:9300;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_http_version 1.1;
        proxy_buffering    off;
    }
}

# ── OnlyOffice Document Server ────────────────────────────
server {
    listen 443 ssl;
    server_name onlyoffice.opencloud.local;

    ssl_certificate     /etc/ssl/opencloud/opencloud.local.crt;
    ssl_certificate_key /etc/ssl/opencloud/opencloud.local.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    client_max_body_size 100M;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";
        proxy_http_version 1.1;
        proxy_buffering    off;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/opencloud.conf \
            /etc/nginx/sites-enabled/opencloud.conf

# Remove the default site if still present
sudo rm -f /etc/nginx/sites-enabled/default

sudo nginx -t && sudo systemctl enable nginx && sudo systemctl restart nginx

13. Install OnlyOffice Document Server

# Import GPG key
curl -fsSL https://download.onlyoffice.com/GPG-KEY-ONLYOFFICE \
  | sudo gpg --dearmor -o /usr/share/keyrings/onlyoffice.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/onlyoffice.gpg] \
  https://download.onlyoffice.com/repo/debian squeeze main" \
  | sudo tee /etc/apt/sources.list.d/onlyoffice.list

sudo apt update
sudo apt install -y onlyoffice-documentserver

During installation you will be prompted for a PostgreSQL password. Set a strong password and keep it — you will not need it again for normal use.

14. Configure OnlyOffice port

OnlyOffice ships with its own Nginx config that listens on port 80, which conflicts with our main Nginx. Reconfigure it to use port 8080 instead.

sudo tee /etc/onlyoffice/documentserver/nginx/onlyoffice-documentserver.conf > /dev/null << 'EOF'
upstream onlyoffice-docservice {
    server 127.0.0.1:8000;
    keepalive 64;
}

map $http_host $this_host {
    "" $host;
    default $http_host;
}

map $http_x_forwarded_proto $the_scheme {
    default $http_x_forwarded_proto;
    "" $scheme;
}

map $http_x_forwarded_host $the_host {
    default $http_x_forwarded_host;
    "" $this_host;
}

server {
    listen 0.0.0.0:8080;
    listen [::]:8080;
    server_tokens off;

    location / {
        proxy_pass         http://onlyoffice-docservice;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";
        proxy_set_header   X-Forwarded-Host  $the_host;
        proxy_set_header   X-Forwarded-Proto $the_scheme;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    }
}
EOF

15. Enable WOPI in OnlyOffice

WOPI is the protocol that lets OnlyOffice communicate with OpenCloud's collaboration service to read and write files.

sudo tee /etc/onlyoffice/documentserver/local.json > /dev/null << 'EOF'
{
  "wopi": {
    "enable": true
  },
  "services": {
    "CoAuthoring": {
      "server": {
        "port": 8000
      }
    }
  }
}
EOF

16. Restart all services

# Restart OnlyOffice internal services
sudo supervisorctl restart all

# Restart OnlyOffice's nginx (runs separately from the main nginx)
sudo systemctl restart nginx

# Restart OpenCloud if not already running
sudo systemctl restart opencloud

Check all services are healthy:

sudo systemctl status opencloud
sudo systemctl status nginx
sudo supervisorctl status

17. Trust the self-signed certificate

Browsers and clients will reject the self-signed cert unless you import it into the OS trust store.

On the server itself (and Ubuntu/Debian clients)

sudo cp /etc/ssl/opencloud/opencloud.local.crt \
        /usr/local/share/ca-certificates/opencloud.local.crt
sudo update-ca-certificates

On Windows clients

Copy opencloud.local.crt to the Windows machine
Double-click the file → Install Certificate
Store location: Local Machine
Place in: Trusted Root Certification Authorities
Click Finish → restart your browser

On macOS clients

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain opencloud.local.crt

18. Verify the deployment

Run these checks from the server to confirm every component is reachable:

# OpenCloud web UI (expect HTTP 200 or 302)
curl -sk https://cloud.opencloud.local | head -5

# WOPI discovery endpoint (expect XML output)
curl -sk https://wopiserver.opencloud.local/wopi/discovery | head -5

# OnlyOffice health check (expect: true)
curl -sk https://onlyoffice.opencloud.local/healthcheck

End-to-end test

Open https://cloud.opencloud.local in your browser
Accept the certificate warning (or skip if you imported the cert)
Log in: username admin, password set in Step 5
Upload a .docx or .xlsx file
Click the file — OnlyOffice editor should open inside OpenCloud

19. Maintenance reference

Service management

Action	Command
View OpenCloud logs	`sudo journalctl -u opencloud -f`
Restart OpenCloud	`sudo systemctl restart opencloud`
Stop OpenCloud	`sudo systemctl stop opencloud`
View Nginx logs	`sudo tail -f /var/log/nginx/error.log`
Restart Nginx	`sudo systemctl restart nginx`
View OnlyOffice logs	`sudo tail -f /var/log/onlyoffice/documentserver/*.log`
Restart OnlyOffice	`sudo supervisorctl restart all`

Upgrade OpenCloud

OC_VERSION="x.y.z"   # new version number
ARCH="amd64"

sudo systemctl stop opencloud

sudo curl -L -o /opt/opencloud/bin/opencloud \
  "https://github.com/opencloud-eu/opencloud/releases/download/v${OC_VERSION}/opencloud-${OC_VERSION}-linux-${ARCH}"

sudo chmod +x /opt/opencloud/bin/opencloud
sudo systemctl start opencloud

Backup

sudo systemctl stop opencloud

sudo tar -czf opencloud-backup-$(date +%Y%m%d).tar.gz \
  /etc/opencloud \
  /var/lib/opencloud

sudo systemctl start opencloud

File locations

What	Path
OpenCloud binary	`/opt/opencloud/bin/opencloud`
OpenCloud config	`/etc/opencloud/opencloud.yaml`
Environment variables	`/etc/opencloud/opencloud.env`
App registry	`/etc/opencloud/app-registry.yaml`
CSP policy	`/etc/opencloud/csp.yaml`
User data / files	`/var/lib/opencloud`
Systemd unit	`/etc/systemd/system/opencloud.service`
Nginx config	`/etc/nginx/sites-available/opencloud.conf`
TLS certificate	`/etc/ssl/opencloud/opencloud.local.crt`
TLS private key	`/etc/ssl/opencloud/opencloud.local.key`
OnlyOffice local config	`/etc/onlyoffice/documentserver/local.json`
OnlyOffice nginx config	`/etc/onlyoffice/documentserver/nginx/onlyoffice-documentserver.conf`
OnlyOffice logs	`/var/log/onlyoffice/documentserver/`

arn-ob/opencloud.md

Select an option

No results found