OnlyOffice in the palm of your hand with Docker Compose! – Quick installation guide

Hi! 🚀 In today’s post, we’re going to learn how to quickly and easily install and utilize office suites that are staples of modern life, especially OnlyOffice, a powerful open source alternative, using Docker Compose 💻 If you’ve ever wanted to collaboratively work on documents, spreadsheets, presentations, and more on the web, this post is for you!

—.

📝 Table of Contents

1. **What is OnlyOffice?
   • Why Choose OnlyOffice?
   • Explore key features
2. **Why Docker Compose?
   • Benefits of Docker Compose
   • Why Docker Compose is especially useful for OnlyOffice installations
3. Steps to set up OnlyOffice Docker Compose.
   • Check prerequisites ✅
   • Create the docker-compose.yml file
     • Document Server vs. Community Server (which one to choose?)
     • Analyze the docker-compose.yml file in detail
     • Setting up JWT Secret: the key to security 🔒.
   • Directory structure and volume setup
4. Run and verify OnlyOffice **Run and verify OnlyOffice
   • Starting the container
   • Verify and access the installation
   • **⚠️ Important: OnlyOffice Document Server is a standalone, no UI!
5. Frequently Asked Questions (FAQs) and Troubleshooting 💡
   • Resolve port conflicts
   • Troubleshooting JWT errors
   • Performance issues and memory allocation
   • HTTPS (SSL) settings
   • Integration with Nextcloud, OwnCloud, etc.
   • How to update OnlyOffice
6. **Conclusion: Start building your own office environment!

—.

1. What is OnlyOffice?

OnlyOffice is a powerful online office suite that is highly compatible with Microsoft Office and includes a word processor, spreadsheet, and presentation editor. It is particularly well suited for team projects or collaborative environments, as its real-time collaboration feature allows multiple users to work on documents simultaneously.

Learn more at #### Why Choose OnlyOffice?

• High MS Office compatibility: Almost full support for MS Office files, including DOCX, XLSX, PPTX, etc.
• Real-time collaboration: Multiple people can edit the same document at the same time and see changes instantly. Learn more at 🗣️
• Open source: The core functionality is open source and free to use and customize.
• Self-hosted: Rather than entrusting your data to a cloud service, you can install it directly on your personal or company server and have data sovereignty. 🛡️
• Multiple integrations: Easily integrates with various document management systems such as Nextcloud, OwnCloud, SharePoint, etc.

Explore key features

• Document Editor: Provides powerful document editing features with an interface similar to MS Word. ✍️
• Spreadsheet Editor: Supports advanced functions and charting features like MS Excel. 📊
• Presentation Editor: Provides slide editing and animation features similar to MS PowerPoint. 🎬

—.

2. Why Docker Compose?

Docker Compose is a tool for defining and running multiple Docker containers. You can use YAML files to configure and deploy your application’s services, networks, volumes, and more all at once.

You can learn more about Docker Compose here: #### Benefits of Docker Compose

• Easy setup: Simplify the deployment process by managing complex commands to run multiple containers in a single YAML file.
• Environment Independence: Encapsulates applications and their dependencies into containers, ensuring they work the same in any environment.
• Reusability and portability: Once written, the docker-compose.yml file can be reused exactly the same on other servers, making deployment easy.
• Dependency management: Dependencies between services (e.g., the web server must start before the database) can be easily defined.

Why Docker Compose is particularly useful for OnlyOffice installations

OnlyOffice Document Server is a complex application in itself, and requires a database (such as PostgreSQL) for stable operation. In addition, in real-world use, you often need to consider interfacing with a web server (such as Nginx) or integration with other services (such as Nextcloud).

Docker Compose enables us to manage the OnlyOffice Document Server and PostgreSQL database as one logical unit, making it easy to start and stop the entire service with just one line of command: docker-compose up. Β

—.

3. Steps to set up OnlyOffice Docker Compose

Now let’s get down to business and set up OnlyOffice with Docker Compose.

Check the prerequisites ✅

Before we get started, you need to make sure you have the following installed on your server (or local PC)

1. Docker: container runtime environment.
   • Verify installation: docker version
2. Docker Compose: A tool for managing multiple containers.
   • Install check: docker compose version (Newer versions use the docker compose command instead of docker-compose) 3.

If it is not installed, please refer to the official Docker documentation to install it.

Create a docker-compose.yml file

There are two main versions of OnlyOffice:

• Document Server: Provides document editing functionality only, and must be used in conjunction with another document management system (such as Nextcloud). Most commonly used.
• Community Server: Provides document editing capabilities as well as its own portal features such as project management, CRM, mail, calendaring, etc. Much heavier and requires a lot of resources.

This guide aims to install Document Server, which is the most common and lightweight.

First, create a directory to store OnlyOffice related files. For example, you can create something like /opt/onlyoffice.

mkdir -p /opt/onlyoffice
cd /opt/onlyoffice

Now create a docker-compose.yml file and fill in its contents.

# /opt/onlyoffice/docker-compose.yml
version: '3.8'

services:
  # OnlyOffice Document Server (document editing capabilities).
  onlyoffice-document-server:
    container_name: onlyoffice-document-server
    image: onlyoffice/documentserver:latest
    ports:
      - "80:80" # Web access port (can be changed to any port you want).
      - "443:443" # HTTPS port (when using SSL/TLS)
    environment:
      # Set JWT secret key (required! See description below).
      - jwt_secret=${onlyoffice_jwt_secret}
      # JWT header name (default Authorization)
      # - JWT_HEADER=${ONLYOFFICE_JWT_HEADER}
      # enable/disable JWT validation (default true)
      # - JWT_ENABLE=true
      # Set database (required when using external DB)
      # - DB_TYPE=PostgreSQL
      # - DB_HOST=onlyoffice-postgres
      # - DB_PORT=5432
      # - DB_NAME=onlyoffice
      # - DB_USER=onlyoffice
      # - db_pwd=${postgres_password}
    volumes:
      - ./data/onlyoffice/logs:/var/log/onlyoffice # Logs.
      - ./data/onlyoffice/data:/var/www/onlyoffice/Data # Document data
      - ./data/onlyoffice/lib:/var/lib/onlyoffice # Libraries
      - ./data/onlyoffice/db:/var/lib/postgresql # PostgreSQL data (when using built-in DB)
    depends_on:
      - # onlyoffice-postgres # depends on PostgreSQL container.
    networks:
      - onlyoffice-network
    restart: always

  # PostgreSQL database (to store internal data for OnlyOffice Document Server)
  onlyoffice-postgres:
    container_name: onlyoffice-postgres
    image: postgres:13
    environment:
      # set PostgreSQL database name, user, and password (required!).
      - POSTGRES_DB=onlyoffice
      - POSTGRES_USER=onlyoffice
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} # Imported from .env file
    volumes:
      - ./data/postgres:/var/lib/postgresql/data # Persistent storage of PostgreSQL data.
    networks:
      - onlyoffice-network
    restart: always

volumes:
  # The volumes defined above are not included here, they are managed directly as container volumes.
  # If you want to use named volumes, you need to define them here.

networks:
  # onlyoffice-network:
    driver: bridge # Network for inter-container communication.

docker-compose.yml File Detailed Analysis

• version: '3.8': Defines the version of the Docker Compose file. It is recommended to use the latest version.
• services:
  • onlyoffice-document-server: The core container that provides the OnlyOffice document editing functionality.
    • container_name: Specifies the name of the container.
    • image: onlyoffice/documentserver:latest: Use the official image of the OnlyOffice Document Server. The latest tag always means the latest version; if you want a specific version, you can specify it like onlyoffice/documentserver:7.4.1.
    • ports: Maps ports in the format host_port:container_port.
      • "80:80": Connect port 80 on the host to port 80 on the container. OnlyOffice will be accessed through this port.
      • "443:443": This is the port for HTTPS. This will be used later when setting up SSL/TLS.
    • environment: Sets environment variables that will be used inside the container. **Especially JWT_SECRET is important!
      • DB-related environment variables such as DB_TYPE, DB_HOST, etc. are commented out because Document Server uses PostgreSQL with embedded Document Server by default. In the above setup, we have set them via depends_on so that a separate onlyoffice-postgres service is connected internally.
    • volumes: Maps volumes between the host and the container for data persistence.
      • ./data/onlyoffice/logs: Stores the container’s logs in ./data/onlyoffice/logs on the host.
      • ./data/onlyoffice/data: This is where you store important document data. **Never delete this!
      • ./data/onlyoffice/lib: Stores library files.
      • ./data/onlyoffice/db: This is where you store your PostgreSQL data. (If you use the onlyoffice-postgres service, it’s better to use the volume of the onlyoffice-postgres service; commenting out or removing it here will reduce confusion.)
    • depends_on: Defines a dependency so that the onlyoffice-postgres service is started first, and then onlyoffice-document-server is started.
    • networks: Connect to a user-defined network called onlyoffice-network to enable internal communication with other services on the same network.
    • restart: always: Sets the container to always restart automatically when the container is shut down or the Docker daemon is restarted.
  • onlyoffice-postgres: A PostgreSQL database container that stores the internal data of OnlyOffice Document Server.
    • image: postgres:13: Uses PostgreSQL version 13.
    • environment: Variables for initializing the database.
      • postgres_db, postgres_user, postgres_password: Set the database name, user, and password. The POSTGRES_PASSWORD is very important, and you should use a strong password. * POSTGRES_PASSWORD: Set the database name, user, and password.
    • volumes: ./data/postgres:/var/lib/postgresql/data: Stores PostgreSQL data permanently on the host. Backing up this directory allows you to restore the database.
    • networks: Connects to onlyoffice-network.
    • restart: always: Ensures that the container is always restarted.
• networks:
  • onlyoffice-network: A user-defined network set to driver: bridge. The onlyoffice-document-server and onlyoffice-postgres will communicate with each other over this network.

Setting up a JWT Secret: The key to security 🔒

OnlyOffice Document Server uses JSON Web Tokens (JWT) for added security. When interfacing with external applications (such as Nextcloud), this secret key is used to authenticate communication. This secret key must be set, and it must be a long, unpredictable string of characters.

1. Generate a secret key: **Create a secret key You can use the following command to generate a randomized secret key.

   openssl rand -hex 32

   Example output: e9a0c6f5d2b1a87e0f9c8d7b6a5e4d3c2b1a0f9e8d7c6b5a4e3d2c1b0a9f8e7d (This is an example, a different value will be generated each time).

2. Create an .env file: **Create a .env file You can use the generated secret key directly in the docker-compose.yml file, but it is better for security to manage it as an environment variable using an .env file. Create an .env file in the same directory as the docker-compose.yml file.

   # /opt/onlyoffice/.env
   ONLYOFFICE_JWT_SECRET="Paste generated JWT secret key here"
   POSTGRES_PASSWORD="Enter a strong PostgreSQL password here"

   Caution: The .env file contains sensitive information, so you should be careful not to expose it to the outside world. It should be managed by adding it to .gitignore when placed in a Git repository, etc.

Directory Structure and Volume Settings

The docker-compose.yml file above assumes the following directory structure.

/opt/onlyoffice/
├── docker-compose.yml
├── .env
└── data/
    ├── onlyoffice/ # Data related to OnlyOffice Document Server
    │ ├── logs/
    │ ├── data/
    │ └── lib/
    └── postgres/ # Data related to PostgreSQL database

The data directory and its subdirectories are created automatically when the docker-compose up command is run.

—]

4. Run and verify OnlyOffice

You are now all set up. Start the OnlyOffice containers by running the following command in the /opt/onlyoffice directory where the docker-compose.yml file is located.

docker compose up -d

• up: Create and start the service defined in the docker-compose.yml file.
• -d: Run in the background in detached mode.

Verify that the container started successfully.

docker compose ps

If the output shows the status of the onlyoffice-document-server and onlyoffice-postgres containers as Up, you are good to go.

name command service status ports
onlyoffice-document-server "/usr/bin/docsrv_sta..." onlyoffice-document-server running 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
onlyoffice-postgres "docker-entrypoint.s..." onlyoffice-postgres running 5432/tcp

It’s also a good idea to check the logs to make sure there are no errors.

docker compose logs -f onlyoffice-document-server

Verify and access the #### installation

Open a web browser and try accessing the following address

• http://localhost (or http://서버_IP_주소 if you’re connecting from the server’s IP address).

If you are successfully connected, you should see the welcome page of the OnlyOffice Document Server. This page indicates that the Document Server is working well.

⚠️ Important: OnlyOffice Document Server stands alone and has no UI!

OnlyOffice Document Server acts as a document editor engine by itself, which means it does not provide a user interface (UI) that allows you to upload or create documents directly from your web browser.

To utilize OnlyOffice Document Server, you must integrate it with another application (e.g., Nextcloud, OwnCloud, Confluence, or a homegrown web application) These applications are responsible for sending documents to Document Server for editing and receiving them back when editing is complete.

So if you’ve reached http://localhost above and seen the welcome page, you’ve successfully installed OnlyOffice Document Server. The next step is to integrate it with the solution of your choice.

—.

5. Frequently Asked Questions (FAQs) and Troubleshooting 💡

1. Troubleshooting Port Conflicts 🚦

• Problem: I get an error like Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use. and I get a message that port 80 is not available.
• Solution: Port 80 on the server is already in use by another service (e.g., Nginx, Apache web server). Change 80:80 to another port (for example, 8080:80) in the ports section of the docker-compose.yml file.

  # ...
  ports:
    - "8080:80" # use port 8080 on host.
    - "443:443"
  # ...

  After making these changes, you should be able to connect to http://localhost:8080.

2. Resolving JWT errors ❌

• Problem: An error message such as “Bad Request. Document editing service cannot be reached.” or “Document editing service is unavailable.” appears, or the document does not open in the associated service.
• Workaround:**
  • Ensure that the ONLYOFFICE_JWT_SECRET variable is set correctly in the .env file.
  • Make sure that JWT_SECRET=${ONLYOFFICE_JWT_SECRET} is defined correctly in the docker-compose.yml file.
  • Make sure that the same JWT Secret key is set in the external application you want to integrate with (Nextcloud, etc.), otherwise an authentication error will occur.
  • Check the logs of the OnlyOffice Document Server container (docker compose logs onlyoffice-document-server) to see if there are any JWT-related error messages.

3. Performance issues and memory allocation 🐢

• Problem: Slow document editing, or slow response when multiple users are connected at the same time.
• Solution: OnlyOffice Document Server can require significant CPU and RAM resources for document conversion and editing operations.
  • RAM: We recommend that you allocate at least 4 GB of RAM.
  • CPU: Ensure that enough cores are allocated.
  • You can set resource limits on Docker containers to prevent certain containers from taking up too many resources. You can add a deploy section to docker-compose.yml.

    # ...
    services:
    # ... onlyoffice-document-server:
    # ...
    deploy:
      resources:
        limits:
          memory: 4G # 4 GB memory limit
          cpus: '2.0' # 2 core limit
    # ...

4. Set up HTTPS (SSL) 🔐.

• Problem: OnlyOffice Document Server works with HTTP by default, which is vulnerable to security.
• Solution: In production environments, HTTPS must be enforced. It is usually best to put a reverse proxy such as Nginx Proxy Manager or Caddy in front of OnlyOffice Document Server to obtain and manage SSL certificates.
  • Nginx Proxy Manager example: **1.
    1. Install the Nginx Proxy Manager container.
    2. Create a new Proxy Host in Nginx Proxy Manager.
    3. in Domain Names, enter the domain you want OnlyOffice to access (for example, docs.yourdomain.com).
    4. set the Scheme to http, the Forward Hostname/IP to onlyoffice-document-server (the name inside your Docker Compose network) or your server IP, and the Forward Port to 80.
    5. On the SSL tab, use Let’s Encrypt to issue an SSL certificate and enable “Force SSL”. With this setup, you can securely access OnlyOffice at https://docs.yourdomain.com.

5. Integration with Nextcloud, OwnCloud, etc.

• Problem: I have installed OnlyOffice Document Server, but I don’t know where I can actually create and view documents.
• Solution: As explained above, OnlyOffice Document Server is a backend engine; the actual user interface is provided by your document management system, such as Nextcloud, OwnCloud, Confluence, SharePoint, etc.
  • Nextcloud Integration Example: * 1.
    1. Install a Nextcloud server.
    2. Go to “Apps” on the Nextcloud admin page and install the “ONLYOFFICE” app.
    3. enter the installed ONLYOFFICE app settings and enter your OnlyOffice Document Server address (http://서버_IP_주소 or https://docs.yourdomain.com) in the “ONLYOFFICE Document Server address” field.
    4. In “Secret key”, enter the same value as ONLYOFFICE_JWT_SECRET that you set in the .env file. The OnlyOffice Document Server will be used when creating or editing documents in Nextcloud from now on.

6. How to update OnlyOffice 🔄

• Solution: With Docker Compose, updating is very simple.
  1. download the latest OnlyOffice image.

     docker compose pull

  2. Stop the currently running container and restart it with the new image.

     docker compose up -d

     During this process, no data is lost because it is stored on the volume.

—]

6. Conclusion: Build your own office environment!

Congratulations! 🎉 You’ve now successfully installed OnlyOffice Document Server using Docker Compose and learned basic troubleshooting. You’ve laid the foundation for building your own powerful document editing and collaboration environment without relying on cloud services.

OnlyOffice is more than just document editing, it offers great benefits for team collaboration and data sovereignty. The synergies are even greater when paired with a cloud storage solution like Nextcloud.

We hope this guide has given you a taste of the power of OnlyOffice and Docker Compose, and that it will help you lead a more productive digital life! If you have any questions, feel free to ask us. Happy Self-Hosting! ✨