Deploying Collabora Online

Introduction

Collabora Online is a powerful, open-source office suite that brings LibreOffice to the browser. It enables real-time collaborative editing of documents, spreadsheets, and presentations directly in your web applications. Built on LibreOffice’s proven technology, Collabora Online provides a robust alternative to proprietary online office solutions while keeping your data under your control.

Collabora Online shines in several key areas:

Document Compatibility: Full support for Microsoft Office formats (DOCX, XLSX, PPTX) and OpenDocument formats (ODT, ODS, ODP), maintaining formatting fidelity across platforms.

Real-Time Collaboration: Multiple users can edit the same document simultaneously with live cursor tracking, change highlighting, and instant synchronization.

Self-Hosted Privacy: Complete data sovereignty with no external dependencies or third-party access to your documents.

Deep Integration: Seamless integration with popular platforms like Nextcloud, ownCloud, Seafile, and custom applications via WOPI protocol.

Feature-Rich Editing: Track changes, comments, version history, templates, mail merge, and advanced formatting tools.

Universal Access: Browser-based interface works on any device without installing software, supporting desktop and mobile browsers.

This guide walks you through deploying Collabora Online on Klutch.sh using Docker. You’ll learn how to configure the server, integrate with cloud storage platforms, implement security measures, optimize performance, and handle production workloads effectively.

Prerequisites

Before deploying Collabora Online, make sure you have:

A Klutch.sh account with dashboard access
A GitHub account for repository hosting
Docker installed locally for testing (optional but recommended)
Basic understanding of web servers and domain configuration
A host application like Nextcloud or ownCloud (if integrating with existing setup)
Domain name for your Collabora instance (recommended for production)
Understanding of WOPI protocol basics (for custom integrations)

Understanding Collabora Online

Architecture Overview

Collabora Online consists of several components working together:

Core Components:

LibreOffice core engine for document processing
LOOL (LibreOffice Online) WebSocket daemon for real-time communication
Cool (Collabora Online) server handling HTTP/WebSocket connections
Document rendering and conversion services
Multi-process architecture for isolation and security

Communication Flow:

Client browser connects to Collabora Online via WebSocket
Collabora communicates with host application using WOPI protocol
Documents are loaded, edited, and saved back to host storage
Real-time updates synchronized between all active users

WOPI Protocol: The Web Application Open Platform Interface (WOPI) is the standard protocol that enables Collabora Online to integrate with file hosting platforms. It handles:

Document discovery and metadata
File access and locking
User authentication and permissions
Save operations and version control

Key Features

Document Editing:

Word processing with advanced formatting
Spreadsheet calculations and charting
Presentation creation and editing
PDF viewing and annotation
Form filling and template support

Collaboration Tools:

Real-time co-editing with multiple users
User presence indicators and cursor tracking
Comments and change tracking
Version history and restore
Chat and communication (when integrated)

Security Features:

End-to-end encryption support
Secure WebSocket connections (WSS)
User authentication via host platform
Granular access control
Isolated document processing

Administrative Capabilities:

Resource usage monitoring
Concurrent user limits
Memory and CPU management
Logging and diagnostics
Performance metrics

Installation and Setup

Step 1: Create Your Project Directory

Start by creating a dedicated directory for your Collabora deployment:

mkdir collabora-deployment
cd collabora-deployment
git init

Step 2: Project Structure

Set up a clean project structure:

mkdir -p config logs

Your project should look like this:

collabora-deployment/
├── Dockerfile
├── .dockerignore
├── .gitignore
├── config/
│   └── coolwsd.xml (optional custom config)
└── logs/
    └── (application logs)

Step 3: Create the Dockerfile

Create a Dockerfile in your project root. Collabora provides official Docker images that we’ll use as our base:

# Use official Collabora Online image
FROM collabora/code:latest

# Set environment variables for configuration
ENV username=admin
ENV password=secure_password
ENV extra_params=--o:ssl.enable=false --o:ssl.termination=true

# Expose the Collabora port
EXPOSE 9980

# Health check to ensure service is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:9980/ || exit 1

# The base image already has CMD defined, no need to override

Important Configuration Notes:

username and password: Admin credentials for the Collabora admin console
extra_params: Additional configuration options
--o:ssl.enable=false: Disable SSL in Collabora (Klutch.sh handles SSL/TLS)
--o:ssl.termination=true: Tell Collabora that SSL is terminated at the proxy
Port 9980: Default Collabora Online port

Step 4: Advanced Dockerfile (Production)

For production deployments with custom configuration, use this enhanced Dockerfile:

# Use official Collabora Online image
FROM collabora/code:latest

# Install additional utilities
USER root
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Set up configuration directory
RUN mkdir -p /etc/coolwsd

# Copy custom configuration if available
COPY config/coolwsd.xml /etc/coolwsd/coolwsd.xml 2>/dev/null || true

# Set environment variables
ENV username=admin
ENV password=change_this_password
ENV dictionaries=en_US
ENV extra_params=--o:ssl.enable=false --o:ssl.termination=true --o:logging.level=warning

# Allow list configuration
# Format: protocol://domain:port or domain:port
# Use escaping: protocol\\:\\/\\/domain\\:port
# Multiple domains separated by spaces
ENV aliasgroup1=https://nextcloud\\.example\\.com:443

# Resource limits
ENV MAX_CONNECTIONS=20
ENV MAX_DOCUMENTS=10

# Expose Collabora port
EXPOSE 9980

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:9980/ || exit 1

# Switch back to coolwsd user
USER cool

# Start Collabora Online
CMD ["/start-collabora-online.sh"]

Environment Variables Explained:

dictionaries: Spell-check dictionaries to enable (e.g., en_US de_DE fr_FR)
aliasgroup1: Allowed domains that can connect to Collabora (security feature)
MAX_CONNECTIONS: Maximum concurrent connections
MAX_DOCUMENTS: Maximum documents that can be open simultaneously
extra_params: Pass any additional LOOL configuration options

Step 5: Create Configuration File (Optional)

For advanced configuration, create config/coolwsd.xml:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <!-- Server settings -->
    <server>
        <name>Collabora Online</name>
        <socket desc="Socket settings">
            <port desc="Port number" type="int" default="9980">9980</port>
        </socket>
    </server>

    <!-- Storage settings -->
    <storage>
        <filesystem allow="true" />
        <wopi desc="Allow/deny wopi storage">
            <host desc="Regex pattern of hostname to allow or deny" allow="true">.*</host>
            <max_file_size desc="Maximum document size in bytes" type="uint">0</max_file_size>
        </wopi>
    </storage>

    <!-- Logging -->
    <logging>
        <level type="string" desc="Log level" default="warning">warning</level>
        <file enable="true">
            <property name="path" desc="Log file path">/var/log/coolwsd.log</property>
        </file>
    </logging>

    <!-- Performance tuning -->
    <per_document>
        <max_concurrency desc="Max number of threads per document" type="uint" default="4">4</max_concurrency>
    </per_document>

    <!-- Security -->
    <ssl>
        <enable type="bool" desc="Enable SSL" default="false">false</enable>
        <termination desc="SSL termination at proxy" type="bool" default="true">true</termination>
    </ssl>
</config>

This configuration provides more granular control over Collabora’s behavior, though the environment variables approach is simpler for most deployments.

Step 6: Create .dockerignore

Create a .dockerignore file to exclude unnecessary files:

.git
.gitignore
.env
*.log
logs/
*.md
README.md
.DS_Store
.vscode
.idea

Step 7: Create .gitignore

Create a .gitignore file to prevent committing sensitive data:

# Logs
*.log
logs/

# Environment files
.env
.env.local
.env.production

# OS files
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/
*.swp

# Custom config with credentials
config/coolwsd.xml

Step 8: Local Testing (Optional)

Test your Collabora setup locally before deploying:

# Build the image
docker build -t collabora-test .

# Run locally
docker run -d \
  --name collabora \
  -p 9980:9980 \
  -e "username=admin" \
  -e "password=testpass123" \
  -e "aliasgroup1=localhost" \
  -e "extra_params=--o:ssl.enable=false" \
  collabora-test

# Check if running
docker ps

# View logs
docker logs -f collabora

# Test the endpoint
curl http://localhost:9980/

# Access admin console
# Open http://localhost:9980/browser/dist/admin/admin.html
# Login with username=admin, password=testpass123

# Cleanup
docker stop collabora
docker rm collabora

Step 9: Commit to GitHub

Push your configuration to GitHub:

git add Dockerfile .dockerignore .gitignore
git commit -m "Add Collabora Online Docker configuration"
git branch -M main
git remote add origin https://github.com/yourusername/collabora-deployment.git
git push -u origin main

Deploying to Klutch.sh

Now let’s deploy Collabora Online to Klutch.sh with proper configuration.

Deployment Steps

Access Klutch.sh Dashboard
Navigate to klutch.sh/app and sign in with your GitHub account.
Create a New Project
In the Projects section, click “Create Project” and name it something like “Collabora Server” or “Document Editor”.
Create a New App
Within your project, click “Create App” to begin configuring your Collabora deployment.
Connect Your Repository
- Select GitHub as your Git source
- Choose the repository containing your Dockerfile
- Select the branch to deploy (typically main)
Klutch.sh will automatically detect the Dockerfile in your repository root.
Configure Traffic Settings
- Traffic Type: Select HTTP (Collabora serves web traffic via HTTP/WebSockets)
- Internal Port: Set to 9980 (Collabora’s default listening port)

Configure Environment Variables

Add the following environment variables to configure your Collabora instance:

Basic Configuration:

# Admin credentials for Collabora admin console
username=admin
password=your-secure-admin-password-here

# SSL configuration (Klutch.sh handles SSL/TLS)
extra_params=--o:ssl.enable=false --o:ssl.termination=true --o:logging.level=warning

Allow List Configuration (Critical for Security):

The aliasgroup variables define which domains can connect to your Collabora instance. This is a crucial security feature.

# Single domain example (Nextcloud instance)
aliasgroup1=https://nextcloud\\.example\\.com:443

# Multiple domains example
aliasgroup1=https://nextcloud\\.example\\.com:443
aliasgroup2=https://cloud\\.mysite\\.com:443
aliasgroup3=https://owncloud\\.company\\.org:443

# Development (allow all - NOT for production)
aliasgroup1=.*

Important: The domain format uses escaped characters:

Dots must be escaped: \\. instead of .
Colons must be escaped: \\: instead of :
Format: https\\:\\/\\/domain\\.com\\:443

Resource Limits:

# Maximum concurrent connections
MAX_CONNECTIONS=20

# Maximum documents open simultaneously
MAX_DOCUMENTS=10

# Memory per document (in MB)
MEMORY_USAGE=200

Language and Dictionaries:

# Space-separated list of language dictionaries
dictionaries=en_US en_GB de_DE fr_FR es_ES it_IT

# Default language
LANG=en_US.UTF-8

Advanced Options:

# File size limits (in bytes, 0 = unlimited)
MAX_FILE_SIZE=104857600
# 100MB

# Idle timeout (in seconds)
IDLE_TIMEOUT=3600

# User idle timeout
USER_IDLE_TIMEOUT=900

# Enable file versioning
FILE_VERSIONING=true

# Logging level (none, fatal, critical, error, warning, notice, information, debug, trace)
LOGLEVEL=warning

Security Recommendations:

Use a strong, unique admin password
Configure specific domains in aliasgroup (never use .* in production)
Set reasonable resource limits based on your expected usage
Keep logging at warning or error for production
Change default credentials immediately after deployment

Configure Compute Resources
Collabora Online is resource-intensive. Choose appropriate resources:

Small Deployment (1-5 concurrent users):
- CPU: 2 cores
- RAM: 4 GB
- Suitable for: Personal use, small teams
Medium Deployment (5-20 concurrent users):
- CPU: 4 cores
- RAM: 8 GB
- Suitable for: Small to medium organizations
Large Deployment (20-50 concurrent users):
- CPU: 8 cores
- RAM: 16 GB
- Suitable for: Larger organizations, departments
Enterprise (50+ concurrent users):
- CPU: 16+ cores
- RAM: 32+ GB
- Suitable for: Enterprise-wide deployments
Note: Each concurrent document editing session uses approximately 200-400MB of RAM. Plan accordingly.
Deploy the Application
Click “Create” to start deployment. Klutch.sh will:
1. Clone your repository from GitHub
2. Detect and build the Dockerfile
3. Configure environment variables
4. Start the Collabora Online container
5. Assign a public URL (e.g., example-app.klutch.sh)
6. Set up automatic HTTPS with SSL certificates
Deployment typically takes 2-4 minutes.
Monitor Deployment
Track the deployment progress:
- Go to the Deployments tab
- View real-time build logs
- Wait for status to show “Running”
- Check for any errors or warnings
Verify Installation
Once deployed, verify Collabora is working:
1. Access your app URL: https://example-app.klutch.sh
2. You should see the Collabora Online welcome page
3. Access the admin console: https://example-app.klutch.sh/browser/dist/admin/admin.html
4. Login with your admin credentials
5. Review the dashboard for system status
6. Check “Active documents” shows 0
7. Verify “Server uptime” is displayed
If you see the admin console, Collabora Online is running successfully.
Test Document Editing
Test basic functionality (requires integration setup, covered in next section):
1. Connect from your host application (Nextcloud/ownCloud)
2. Open a test document
3. Verify document loads in browser
4. Test editing and saving
5. Test real-time collaboration with another user
6. Check admin console shows active documents

Integration with Host Applications

Collabora Online needs to be connected to a file hosting platform. Here’s how to integrate with popular platforms.

Nextcloud Integration

Nextcloud is the most common integration for Collabora Online.

Step 1: Install Collabora Online App

In Nextcloud:

Go to Apps → Office & text
Search for “Collabora Online”
Install the app
Enable the app

Step 2: Configure Collabora Online App

Go to Settings → Administration → Collabora Online
Select “Use your own server”
Enter your Collabora URL: https://example-app.klutch.sh
Click “Save”

Step 3: Test the Integration

Create a new document in Nextcloud
Click on it to open
Document should open in Collabora Online editor
Try editing and saving
Verify changes are persisted

Troubleshooting Nextcloud Integration:

If documents don’t open:

Check Nextcloud logs: Settings → Logging
Verify Collabora URL is correct (include https://)
Ensure your Nextcloud domain is in Collabora’s aliasgroup
Check network connectivity between Nextcloud and Collabora
Verify SSL certificates are valid

ownCloud Integration

Step 1: Install Collabora App

Download the ownCloud Collabora app
Extract to your ownCloud apps directory

Enable via command line:

sudo -u www-data php occ app:enable richdocuments

Step 2: Configure Connection

Go to Settings → Admin → Collabora Online
Enter Collabora server URL: https://example-app.klutch.sh
Save configuration
Test connection

Step 3: Verify Integration

Upload a test document
Click to open in Collabora
Verify editing works
Check save functionality

Custom Application Integration

For custom applications, implement the WOPI protocol:

Basic WOPI Implementation:

// Example WOPI discovery endpoint
const collaboraUrl = 'https://example-app.klutch.sh';
const discoveryUrl = `${collaboraUrl}/hosting/discovery`;

// Fetch WOPI discovery information
async function getWopiDiscovery() {
  const response = await fetch(discoveryUrl);
  const xml = await response.text();
  // Parse XML to get action URLs for different file types
  return parseWopiDiscovery(xml);
}

// Generate Collabora editor URL
function getEditorUrl(fileId, accessToken) {
  const wopiSrc = `https://your-app.com/wopi/files/${fileId}`;
  const collaboraAction = 'https://example-app.klutch.sh/browser/<action-url>';

  return `${collaboraAction}?WOPISrc=${encodeURIComponent(wopiSrc)}&access_token=${accessToken}`;
}

// WOPI endpoint for file info
app.get('/wopi/files/:fileId', (req, res) => {
  const { fileId } = req.params;
  const accessToken = req.query.access_token;

  // Validate token and get file info
  const fileInfo = {
    BaseFileName: 'document.docx',
    Size: 12345,
    UserId: 'user123',
    UserFriendlyName: 'John Doe',
    UserCanWrite: true,
    PostMessageOrigin: 'https://example-app.klutch.sh',
    SupportsUpdate: true,
    SupportsLocks: true
  };

  res.json(fileInfo);
});

// WOPI endpoint for file contents
app.get('/wopi/files/:fileId/contents', (req, res) => {
  const { fileId } = req.params;
  // Return file contents
  const fileBuffer = getFileBuffer(fileId);
  res.send(fileBuffer);
});

// WOPI endpoint for saving file
app.post('/wopi/files/:fileId/contents', (req, res) => {
  const { fileId } = req.params;
  // Save file contents from request body
  saveFile(fileId, req.body);
  res.json({ LastModifiedTime: new Date().toISOString() });
});

Key WOPI Endpoints to Implement:

CheckFileInfo: GET /wopi/files/{fileid}
- Returns file metadata and permissions
GetFile: GET /wopi/files/{fileid}/contents
- Returns the file binary contents
PutFile: POST /wopi/files/{fileid}/contents
- Saves modified file contents
Lock/Unlock: File locking for concurrent editing

WOPI Protocol Resources:

Security Configuration

Domain Allowlist

The most critical security setting is the domain allowlist. Only domains you specify can connect to Collabora.

Secure Configuration:

# Production - specific domains only
aliasgroup1=https://nextcloud\\.company\\.com:443
aliasgroup2=https://cloud\\.company\\.com:443
aliasgroup3=https://docs\\.company\\.com:443

Format Rules:

Escape dots: \. becomes \\.
Escape colons: : becomes \\:
Escape slashes: / becomes \\/
Complete format: https\\:\\/\\/domain\\.com\\:443

Never use in production:

# Insecure - allows any domain
aliasgroup1=.*

Admin Console Security

The admin console provides system information and should be protected:

Change Default Password: Immediately change the default admin password
Restrict Access: Consider IP whitelisting if possible
Monitor Access: Check admin console logs regularly
Disable if Unused: If you don’t need the admin console, disable it

Disable Admin Console (via custom config):

<admin_console desc="Web admin console settings">
    <enable type="bool" desc="Enable/disable admin console" default="false">false</enable>
</admin_console>

SSL/TLS Configuration

Klutch.sh handles SSL/TLS termination, but ensure proper configuration:

# Collabora configuration for SSL termination
extra_params=--o:ssl.enable=false --o:ssl.termination=true

This tells Collabora:

Don’t handle SSL internally (ssl.enable=false)
SSL is terminated at the reverse proxy (ssl.termination=true)
Trust the proxy’s SSL setup

Resource Limits

Prevent resource exhaustion attacks:

# Connection limits
MAX_CONNECTIONS=20
MAX_DOCUMENTS=10

# Memory limits per document
MEMORY_USAGE=200

# File size limits (100MB)
MAX_FILE_SIZE=104857600

# Idle timeouts
IDLE_TIMEOUT=3600
USER_IDLE_TIMEOUT=900

Access Control

Implement authentication at your host application level:

Validate user tokens before generating WOPI URLs
Use short-lived access tokens
Implement session management
Log all document access
Monitor for suspicious activity

Performance Optimization

Resource Allocation

Memory Management:

Each document editing session consumes memory:

Simple document: ~200MB
Complex document: ~400MB
With images/charts: ~600MB+

Calculate memory needs:

Total RAM = (MAX_DOCUMENTS × Average Memory per Document) + 2GB overhead

Example:
10 documents × 300MB + 2GB = 5GB minimum RAM

CPU Allocation:

Collabora is CPU-intensive:

Document conversion: High CPU
Real-time editing: Moderate CPU
Rendering: High CPU

Recommended CPU cores:

Small (1-5 users): 2 cores
Medium (5-20 users): 4 cores
Large (20-50 users): 8 cores
Enterprise (50+ users): 16+ cores

Concurrent User Management

Set Appropriate Limits:

# For 4GB RAM instance
MAX_CONNECTIONS=10
MAX_DOCUMENTS=8

# For 8GB RAM instance
MAX_CONNECTIONS=20
MAX_DOCUMENTS=15

# For 16GB RAM instance
MAX_CONNECTIONS=40
MAX_DOCUMENTS=30

Monitor Usage:

Check the admin console regularly:

Active documents count
Memory usage per document
CPU utilization
Connection count
Queue length

Caching Strategies

Enable Tile Caching:

Collabora caches rendered document tiles for faster loading:

# Enable tile caching
extra_params=--o:ssl.enable=false --o:ssl.termination=true --o:tile_cache_path=/tmp/tiles

Browser Caching:

Configure your host application to cache Collabora resources:

JavaScript bundles
CSS files
Image assets
Font files

Network Optimization

WebSocket Performance:

Collabora relies heavily on WebSockets:

Ensure WebSocket connections aren’t blocked
Minimize network latency
Use CDN for static assets
Enable compression

Reduce Latency:

Deploy Collabora in the same region as your host application
Use fast storage for document access
Optimize network path between services
Consider connection pooling

Monitoring and Logging

Admin Console Monitoring

Access the admin console at:

https://example-app.klutch.sh/browser/dist/admin/admin.html

Key Metrics to Monitor:

Active Documents: Number of currently open documents
Active Users: Concurrent users editing
Memory Usage: Per document and total
CPU Usage: Overall CPU utilization
Document Queue: Waiting documents
Expired Documents: Cleaned up sessions

Dashboard Interpretation:

Active documents: 5 / 10 (50% capacity)
Active users: 12 / 20 (60% capacity)
Total memory: 2.5GB / 8GB (31% used)
CPU usage: 45%

If you see:

Active documents at 80%+ capacity: Consider increasing MAX_DOCUMENTS
Memory at 85%+ usage: Upgrade RAM or reduce limits
CPU constantly above 70%: Upgrade CPU cores
Queue building up: Scale resources immediately

Application Logs

View Collabora logs through Klutch.sh:

Go to your app in Klutch.sh dashboard
Click on Logs tab
Filter by time range
Search for specific events

Common Log Entries:

# Normal operation
[INF] Document loaded successfully
[INF] User connected: user@example.com
[INF] Document saved: document.docx

# Warnings
[WRN] High memory usage detected
[WRN] Document idle timeout approaching
[WRN] Connection limit reached

# Errors
[ERR] Failed to load document
[ERR] WOPI request failed
[ERR] Memory limit exceeded

Log Levels:

Configure logging verbosity:

# Production (recommended)
extra_params=--o:logging.level=warning

# Development/troubleshooting
extra_params=--o:logging.level=information

# Debug (verbose, only for troubleshooting)
extra_params=--o:logging.level=debug

Performance Metrics

Track Key Performance Indicators:

Document Load Time: Time to open a document
Save Operation Time: Time to save changes
Collaboration Latency: Delay in seeing other users’ changes
Memory per Document: Average RAM usage
CPU per Document: Average CPU usage
Concurrent Sessions: Peak concurrent users

Acceptable Performance Targets:

Document load time: < 3 seconds
Save operation: < 2 seconds
Collaboration latency: < 500ms
Memory per document: 200-400MB
CPU per document: 15-25%

If metrics exceed these targets, investigate:

Resource constraints
Network issues
Document complexity
Integration problems

Health Checks

The Dockerfile includes a health check that Klutch.sh uses:

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:9980/ || exit 1

This checks if Collabora is responding every 30 seconds. If it fails 3 times, the container is marked unhealthy.

Manual Health Check:

# Check if service is responding
curl https://example-app.klutch.sh/

# Expected response: HTML welcome page

# Check WOPI discovery
curl https://example-app.klutch.sh/hosting/discovery

# Expected response: XML with action URLs

Troubleshooting

Issue 1: Documents Won’t Open

Symptoms: Clicking a document shows loading spinner, then error or blank page

Solutions:

Check Domain Allowlist:

# Verify your host domain is in aliasgroup
# Example: If host is nextcloud.example.com
aliasgroup1=https://nextcloud\\.example\\.com:443

Verify WOPI Discovery:
Terminal window
```
curl https://example-app.klutch.sh/hosting/discovery
```
Should return XML with action URLs. If 404 or error, Collabora isn’t running properly.
Check Host Application Logs:
- Nextcloud: Settings → Logging
- Look for WOPI errors or connection failures
- Check for SSL certificate issues
Verify Network Connectivity:
- Ensure host application can reach Collabora
- Check firewall rules
- Test with curl from host server
Check Browser Console:
- Open browser developer tools (F12)
- Look for JavaScript errors
- Check Network tab for failed requests
- Common issue: Mixed content (HTTP/HTTPS)

Issue 2: Admin Console Won’t Load

Symptoms: Admin console shows 404 or doesn’t authenticate

Solutions:

Correct URL Format:

Correct: https://example-app.klutch.sh/browser/dist/admin/admin.html
Wrong: https://example-app.klutch.sh/admin

Check Admin Credentials:
- Verify username and password environment variables
- Password is case-sensitive
- Try resetting credentials
Clear Browser Cache:
- Admin console assets may be cached
- Try incognito/private mode
- Clear browser cache and reload
Check Logs:
- View Collabora logs in Klutch.sh
- Look for authentication errors
- Verify admin console is enabled

Issue 3: Poor Performance or Slow Editing

Symptoms: Slow document loading, laggy typing, delayed saves

Solutions:

Check Resource Usage:
- View Klutch.sh dashboard metrics
- CPU usage consistently high? Upgrade cores
- Memory near limit? Increase RAM or reduce MAX_DOCUMENTS
Review Concurrent Load:
- Check admin console active documents
- If at or near MAX_DOCUMENTS, increase limit or resources
- Consider if limits are appropriate for your resources
Document Complexity:
- Large documents (100+ pages) are slower
- Many images/charts increase memory usage
- Complex spreadsheets with formulas impact performance
- Consider breaking large documents into smaller ones
Network Latency:
- Test network speed between host and Collabora
- If services in different regions, consider co-location
- Check WebSocket connection stability

Reduce Logging Verbosity:

# Switch from debug to warning
extra_params=--o:logging.level=warning

Issue 4: Connection Limit Reached

Symptoms: New users can’t open documents, error about connection limit

Solutions:

Increase Connection Limit:

MAX_CONNECTIONS=40  # Increase from default
MAX_DOCUMENTS=30

Ensure Adequate Resources:
- More connections require more RAM
- Calculate: (MAX_DOCUMENTS × 300MB) + 2GB overhead
- Upgrade instance if needed
Check for Stale Sessions:
- Review admin console for idle documents
- Reduce idle timeouts:
Terminal window
```
IDLE_TIMEOUT=1800  # 30 minutes
USER_IDLE_TIMEOUT=600  # 10 minutes
```
Monitor Usage Patterns:
- Track peak usage times
- Plan capacity for peak load
- Consider time-of-day scaling

Issue 5: File Save Failures

Symptoms: Changes aren’t saved, “save failed” error

Solutions:

Check WOPI Endpoint:
- Verify PutFile endpoint is implemented correctly
- Test with curl or Postman
- Check authentication on save requests
Review File Permissions:
- User must have write permissions
- Check host application file permissions
- Verify WOPI CheckFileInfo returns UserCanWrite: true

File Size Limits:

# Increase if saving large files fails
MAX_FILE_SIZE=209715200  # 200MB

Storage Space:
- Check host application has available storage
- Verify disk space isn’t full
- Monitor storage usage
Check Locks:
- File may be locked by another process
- Implement WOPI lock/unlock properly
- Release stale locks

Issue 6: SSL/Certificate Errors

Symptoms: Certificate warnings, “not secure” messages, mixed content errors

Solutions:

Verify SSL Configuration:
Terminal window
```
extra_params=--o:ssl.enable=false --o:ssl.termination=true
```
Collabora should NOT handle SSL (Klutch.sh does this).
Check URLs:
- All URLs should use https://
- Host application must use HTTPS
- No mixed HTTP/HTTPS content
Certificate Validation:
- Klutch.sh provides automatic SSL certificates
- Wait a few minutes for certificate provisioning
- Verify custom domain DNS is correct
Browser Issues:
- Clear browser cache
- Try different browser
- Check for browser security extensions blocking content

Issue 7: WebSocket Connection Failed

Symptoms: “Connection lost”, frequent disconnections, real-time updates not working

Solutions:

Check WebSocket Support:
- Browser must support WebSockets
- Verify no proxy blocking WebSocket connections
- Test with different network
Review Network Configuration:
- Some corporate firewalls block WebSockets
- Try from different network
- Check if VPN interferes

Timeout Settings:

# Increase WebSocket timeout
extra_params=--o:ssl.enable=false --o:ssl.termination=true --o:net.proto.timeout.secs=120

Connection Stability:
- Monitor for network interruptions
- Check for packet loss
- Verify stable internet connection

Issue 8: Memory Errors

Symptoms: “Out of memory” errors, container crashes, documents fail to open

Solutions:

Upgrade RAM:
- Calculate required memory properly
- Each document: 200-400MB average
- Formula: (MAX_DOCUMENTS × 400MB) + 2GB

Reduce Limits:

# Lower concurrent documents
MAX_DOCUMENTS=8  # Reduce from 10
MAX_CONNECTIONS=15  # Reduce from 20

Memory Per Document:

# Reduce if documents are small/simple
MEMORY_USAGE=150  # Reduce from default 200

Monitor Memory Usage:
- Check admin console regularly
- Track memory per document
- Close idle documents faster
Document Optimization:
- Reduce image sizes before uploading
- Avoid extremely large documents
- Break large documents into sections

Issue 9: Integration Authentication Failed

Symptoms: “Authentication failed”, “Access denied”, WOPI errors

Solutions:

Verify Access Tokens:
- Generate tokens correctly in host application
- Tokens must be valid and not expired
- Include token in WOPI requests
Check WOPI Endpoints:
- Verify all required endpoints are implemented
- Test CheckFileInfo returns correct data
- Ensure proper authentication headers
Domain Configuration:
- Host domain must be in Collabora allowlist
- Format must be correct (escaped properly)
- Protocol (http/https) must match
Debug WOPI Requests:
Terminal window
```
# Enable verbose logging
extra_params=--o:logging.level=debug
```
Review logs for WOPI request/response details.

Issue 10: High CPU Usage

Symptoms: CPU constantly at 90%+, slow performance, high load

Solutions:

Upgrade CPU:
- Collabora is CPU-intensive
- Document rendering uses significant CPU
- Multiple concurrent users need multiple cores

Reduce Concurrent Load:

MAX_DOCUMENTS=5  # Limit concurrent documents

Optimize Documents:
- Large PDFs or images consume CPU
- Complex spreadsheets with many formulas
- Reduce document complexity
Check for Runaway Processes:
- Review admin console
- Look for stuck documents
- Restart container if necessary
Monitor Patterns:
- Identify peak usage times
- Plan resources for peak load
- Consider scaling during high-demand periods

Custom Domains

Using a custom domain makes your Collabora instance more professional and easier to remember.

Step 1: Add Domain in Klutch.sh

Go to your app in Klutch.sh dashboard
Navigate to Domains section
Click “Add Custom Domain”
Enter your domain (e.g., collabora.yourdomain.com)
Save the configuration

Step 2: Configure DNS

Update your DNS provider with a CNAME record:

Type: CNAME
Name: collabora (or your subdomain)
Value: example-app.klutch.sh
TTL: 3600

Example DNS Configuration:

collabora.yourdomain.com.    CNAME    example-app.klutch.sh.
office.yourdomain.com.       CNAME    example-app.klutch.sh.
docs.yourdomain.com.         CNAME    example-app.klutch.sh.

Step 3: Update Integration Settings

After DNS propagates (5-60 minutes):

Nextcloud:

Go to Settings → Collabora Online
Update URL to https://collabora.yourdomain.com
Save and test

ownCloud:

Go to Settings → Collabora Online
Update server URL
Test connection

Custom Integration: Update your application’s Collabora URL configuration to use the new domain.

Step 4: Update Domain Allowlist

Update your Collabora environment variables:

# If host is at custom domain
aliasgroup1=https://nextcloud\\.yourdomain\\.com:443

# Collabora now accessible at
# https://collabora.yourdomain.com

Redeploy after updating environment variables.

Step 5: Verify SSL Certificate

Klutch.sh automatically provisions SSL certificates for custom domains:

Wait 5-10 minutes after DNS propagation
Access https://collabora.yourdomain.com
Verify browser shows secure padlock icon
Check certificate is valid and trusted
Test document opening from host application

Production Best Practices

Scaling Strategies

Vertical Scaling (Single Instance):

Start with vertical scaling for most deployments:

Small Team (< 10 users):
- 2 CPU cores
- 4 GB RAM
- MAX_DOCUMENTS=8
- MAX_CONNECTIONS=15

Medium Organization (10-30 users):
- 4 CPU cores
- 8 GB RAM
- MAX_DOCUMENTS=15
- MAX_CONNECTIONS=30

Large Organization (30-75 users):
- 8 CPU cores
- 16 GB RAM
- MAX_DOCUMENTS=30
- MAX_CONNECTIONS=60

Horizontal Scaling (Multiple Instances):

For very large deployments (75+ concurrent users):

Deploy multiple Collabora instances
Use load balancer to distribute traffic
Each instance handles subset of users
Ensure session affinity (sticky sessions)
Share configuration across instances

Capacity Planning:

Monitor these metrics to determine when to scale:

Scale up when:
- CPU usage consistently > 70%
- Memory usage > 85%
- Active documents > 80% of MAX_DOCUMENTS
- Response times degrading
- Connection limit frequently hit

Scale down when:
- Resources underutilized for extended periods
- Peak usage lower than expected
- Cost optimization needed

Backup and Disaster Recovery

Configuration Backup:

Your Dockerfile and environment variables are your configuration. Keep them in version control:

# Backup configuration
git add Dockerfile .dockerignore
git commit -m "Update Collabora configuration"
git push origin main

# Tag releases
git tag -a v1.0 -m "Production configuration v1.0"
git push origin v1.0

Disaster Recovery Plan:

Document Current Setup:
- Environment variables
- Resource allocation
- Domain configuration
- Integration settings
Test Deployment from Scratch:
- Regularly test deploying from your repository
- Verify all configurations work
- Document any manual steps
Recovery Time Objective (RTO):
- Fresh deployment: 5-10 minutes
- DNS propagation: 5-60 minutes
- Total recovery: < 2 hours
Monitoring and Alerts:
- Set up uptime monitoring
- Alert on extended downtime
- Monitor critical metrics

High Availability Considerations:

For mission-critical deployments:

Run multiple Collabora instances
Use load balancer with health checks
Deploy in multiple regions (if needed)
Maintain hot standby instance
Implement automatic failover

Security Hardening

Essential Security Measures:

Strong Admin Password:

# Use long, random password
password=$(openssl rand -base64 32)

Strict Domain Allowlist:

# Never use .* in production
# Only allow specific, known domains
aliasgroup1=https://nextcloud\\.company\\.com:443

Resource Limits:

# Prevent resource exhaustion
MAX_CONNECTIONS=20
MAX_DOCUMENTS=10
MAX_FILE_SIZE=104857600

Network Security:
- Use HTTPS only
- Enable HSTS headers (Klutch.sh handles this)
- Verify SSL certificates
- No mixed HTTP/HTTPS content
Access Control:
- Implement authentication at host level
- Use short-lived tokens
- Audit document access
- Monitor for suspicious activity

Regular Updates:

# Keep base image updated
FROM collabora/code:latest

# Update regularly
docker pull collabora/code:latest

Security Monitoring:
- Review admin console regularly
- Check for unusual activity
- Monitor failed access attempts
- Track resource usage anomalies

Compliance Considerations:

For regulated industries:

Data Residency: Deploy in required geographic regions
Audit Logging: Enable comprehensive logging
Encryption: Verify end-to-end encryption
Access Controls: Implement strict authentication
Data Retention: Configure according to policies
Regular Audits: Conduct security assessments

Maintenance Schedule

Daily:

Monitor admin console dashboard
Check for errors in logs
Verify active document count is reasonable
Ensure CPU and memory within normal ranges

Weekly:

Review error logs in detail
Check for failed document operations
Monitor storage usage trends
Verify backup configurations
Test document editing from host application

Monthly:

Review and optimize resource allocation
Update Docker image to latest version
Security patch review and application
Performance metrics analysis
Capacity planning review

Quarterly:

Full security audit
Disaster recovery test
Integration testing with host applications
User feedback review
Cost optimization analysis

Update Procedure:

# 1. Check for updates
# Visit Collabora Online release notes

# 2. Update Dockerfile
FROM collabora/code:24.04  # Use specific version tag

# 3. Test in development
# Deploy to test environment first

# 4. Backup current configuration
git commit -am "Pre-update backup"

# 5. Update Dockerfile to new version
# Commit and push to GitHub

# 6. Deploy via Klutch.sh
# Klutch.sh automatically rebuilds and deploys

# 7. Verify functionality
# Test document editing
# Check admin console
# Verify integrations work

# 8. Monitor for issues
# Watch logs for 24-48 hours
# Check performance metrics

# 9. Rollback if needed
git revert HEAD
# Push to trigger redeployment

Performance Tuning

Optimize for Your Use Case:

Document-Heavy Workload (many simultaneous editors):

MAX_DOCUMENTS=20
MAX_CONNECTIONS=30
MEMORY_USAGE=250
IDLE_TIMEOUT=7200

Connection-Heavy Workload (many users, shorter sessions):

MAX_DOCUMENTS=10
MAX_CONNECTIONS=50
MEMORY_USAGE=200
IDLE_TIMEOUT=1800

Resource-Constrained (limited RAM/CPU):

MAX_DOCUMENTS=5
MAX_CONNECTIONS=10
MEMORY_USAGE=150
IDLE_TIMEOUT=900

Advanced Performance Tuning:

# Fine-tune via extra_params
extra_params=--o:ssl.enable=false \
  --o:ssl.termination=true \
  --o:logging.level=warning \
  --o:per_document.max_concurrency=4 \
  --o:per_document.batch_priority=5 \
  --o:per_document.document_signing_url= \
  --o:per_document.redlining_as_comments=false \
  --o:per_view.out_of_focus_timeout_secs=120 \
  --o:per_view.idle_timeout_secs=900

Additional Resources

Conclusion

Deploying Collabora Online on Klutch.sh gives you a powerful, self-hosted document collaboration platform with complete control over your data. You’ve learned how to create a production-ready Dockerfile with proper security configurations, configure environment variables for optimal performance, set up domain allowlists to restrict access, integrate with popular platforms like Nextcloud and ownCloud, implement the WOPI protocol for custom integrations, monitor performance through the admin console, troubleshoot common deployment issues, and scale resources based on user load.

Your Collabora Online instance is now running on Klutch.sh’s infrastructure with automatic HTTPS, reliable hosting, and the flexibility to scale as your needs grow. Whether you’re providing document editing for a small team or serving hundreds of concurrent users in an enterprise environment, you have the foundation for a robust collaboration platform.

The real power of Collabora Online lies in its flexibility and privacy-first approach. Unlike proprietary cloud solutions, you maintain complete control over your documents, can customize the deployment to your specific needs, and ensure compliance with data protection requirements. Combined with Klutch.sh’s straightforward deployment process, you can focus on providing great collaboration tools to your users rather than managing complex infrastructure.

For questions, advanced configurations, or community support, check out the Collabora Online SDK documentation and forums. The active community and comprehensive documentation make it easy to extend your deployment with custom features and integrations.