NixOS OnlyOffice: `enableExampleServer` Bug Explained

Aug 6, 2025 by Luna Greco 54 views

NixOS and OnlyOffice: The `services.onlyoffice.enableExampleServer` Bug

Introduction

Hey guys! Today, we're diving deep into a bug in NixOS related to OnlyOffice, specifically the services.onlyoffice.enableExampleServer option. If you're using NixOS and OnlyOffice, you might have run into this issue, or you might in the future. So, let's get right into it and see what's going on and how we can tackle it. This guide is designed to help you understand the problem, analyze the cause, and hopefully, find a solution or workaround. We'll be covering everything from the initial bug report to expected behavior and potential fixes. The goal is to provide a comprehensive overview that not only addresses the immediate issue but also enhances your understanding of how NixOS and OnlyOffice interact.

The Bug Report

Nixpkgs Version

This bug was reported on the stable Nixpkgs version (25.05). It’s crucial to note the specific version because bugs can be version-specific, and fixes might already be in place in newer versions. Knowing the exact version helps in reproducing the issue and verifying any potential solutions.

Describing the Bug

The core issue revolves around the enableExampleServer option within the OnlyOffice service configuration in NixOS. When this option is enabled, it's expected to set up an example server for OnlyOffice. However, as the bug report highlights, this isn't happening as expected. This discrepancy between the expected and actual behavior is what defines a bug, and it’s important to document it clearly for analysis and resolution.

NixOS Configuration

Here's the configuration snippet that triggers the bug:

services.onlyoffice = {
 enable = true;
 enableExampleServer = true;
 examplePort = 1234;
};

This configuration block is placed in /etc/nixos/configuration.nix, which is the main configuration file for NixOS systems. The intention here is clear: enable OnlyOffice with the example server running on port 1234. However, the subsequent behavior demonstrates that the example server doesn't start as expected. This misconfiguration is the root cause of the problem, as it leads to the system attempting to access a service that is not running.

Observed Behavior

With the above configuration, the OnlyOffice document server itself loads correctly at http://localhost/welcome/, returning an HTTP 200 status, which indicates a successful response. This confirms that the main OnlyOffice service is running without issues. However, accessing http://localhost/example results in a 502 HTTP error. This error signifies a Bad Gateway, meaning the server (in this case, Nginx) couldn't connect to the upstream server (the OnlyOffice example server).

The Problem

The 502 error points to a connection issue between Nginx and the expected OnlyOffice example server. Nginx, acting as a reverse proxy, is configured to forward requests to the example server. However, it's unable to establish a connection, indicating that the example server is either not running or not accessible. This is a critical issue because it prevents users from accessing the example server, which is intended to demonstrate OnlyOffice's capabilities and provide a testing environment. Let's keep digging, guys!

Nginx Logs

The Nginx logs provide further clues:

connect() failed (111: Connection refused) while connecting to upstream, client: ::1, server: localhost, request: "GET /example/ HTTP/1.1", upstream: "http://[::1]:1234/", host: "localhost", referrer: "http://localhost/welcome/"
connect() failed (111: Connection refused) while connecting to upstream, client: ::1, server: localhost, request: "GET /example/ HTTP/1.1", upstream: "http://127.0.0.1:1234/", host: "localhost", referrer: "http://localhost/welcome/"

These logs clearly show that Nginx is unable to connect to the upstream server on port 1234, which is the configured examplePort. The "Connection refused" error (111) is a strong indicator that no service is listening on that port. This confirms that the example server, despite being enabled in the configuration, is not actually running. It's a crucial piece of information for diagnosing the bug.

Nginx Configuration

Checking the autogenerated Nginx configuration, we find:

upstream onlyoffice-example {
 server localhost:1234;
}

This snippet shows that Nginx is indeed configured to proxy requests to localhost:1234, which is where the example server should be running. The presence of this upstream configuration further emphasizes that the issue is not with Nginx's setup but rather with the example server itself not being active. This alignment between the intended configuration and the actual Nginx setup narrows down the problem to the example server's initialization.

No Process Listening on Port 1234

Using ss -ltpn | grep 1234 confirms that no process is listening on port 1234. This command checks for listening TCP sockets and filters the output for port 1234. The absence of any output definitively shows that the OnlyOffice example server is not running and listening for connections on the specified port. This is a critical finding that directly contradicts the expectation set by the enableExampleServer option.

The output of ss -ltpn further shows the other services running on the system:

#LISTEN 0 511 0.0.0.0:80 0.0.0.0:*
# users:(("nginx",pid=75746,fd=6),("nginx",pid=75713,fd=6))
#LISTEN 0 244 127.0.0.1:5432 0.0.0.0:*
# users:((".postgres-wrapp",pid=55737,fd=6))
#LISTEN 0 128 127.0.0.1:5672 0.0.0.0:*
# users:(("beam.smp",pid=55665,fd=40))
#LISTEN 0 128 0.0.0.0:25672 0.0.0.0:*
# users:(("beam.smp",pid=55665,fd=25))
#LISTEN 0 511 [::]:80 [::]:*
# users:(("nginx",pid=75746,fd=7),("nginx",pid=75713,fd=7))
#LISTEN 0 511 *:8000 *:* users:(("docservice",pid=55808,fd=24))
#LISTEN 0 4096 *:4369 *:* users:((".epmd-wrapped",pid=55733,fd=3),("systemd",pid=1,fd=283))
#LISTEN 0 244 [::1]:5432 [::]:*
# users:((".postgres-wrapp",pid=55737,fd=5))

This output lists the processes listening on various ports, including Nginx on ports 80, PostgreSQL on port 5432, and the OnlyOffice document service on port 8000. The absence of any process listening on port 1234 reinforces the conclusion that the example server is not running. This comprehensive check eliminates any doubt about the server's status.

No Systemd Service for the Example Server

Further investigation reveals that there's no systemd service for the example server. Running systemctl list-units --type=service | grep onlyoffice shows only the following services:

onlyoffice-converter.service loaded active running onlyoffice converter
onlyoffice-docservice.service loaded active running onlyoffice documentserver

On a Debian/Ubuntu system, we'd expect to see a service like ds-example.service. The absence of such a service in NixOS indicates that the systemd service responsible for managing the example server is not being created. This is a critical piece of the puzzle, as systemd services are the standard way to manage background processes in modern Linux distributions, including NixOS. Without a systemd service, the example server cannot be automatically started and managed.

Analysis of the Issue

Let's break it down, guys. The core issue stems from the fact that while the NixOS module for OnlyOffice declares support for enableExampleServer and examplePort, and even defines an Nginx upstream configuration for it, there's no actual derivation or Nix package for the ExampleServer itself. This means that while the configuration suggests the example server should be running, there's no underlying implementation to make it happen. This discrepancy between configuration and implementation is the root cause of the bug.

Specifically:

The module in nixos/modules/services/web-apps/onlyoffice.nix declares support for enableExampleServer and examplePort.
It conditionally defines an Nginx upstream onlyoffice-example if enableExampleServer = true.
However, and this is crucial, there is no derivation or Nix package for the ExampleServer available. This omission means that no actual service is built or started when the option is enabled.

This analysis highlights a gap in the NixOS module for OnlyOffice. The module has the configuration options and Nginx setup, but it lacks the actual implementation for running the example server. This is a common type of bug in software development, where features are partially implemented but not fully realized. Identifying this gap is the first step towards fixing the bug.

Expected Behavior

So, what should happen when services.onlyoffice.enableExampleServer = true? The following outlines the expected behavior:

Systemd Service Creation: A systemd service, such as onlyoffice-example-server.service or ds-example.service (similar to Debian), should be created. This service would be responsible for managing the lifecycle of the example server, ensuring it starts on boot and restarts if it crashes.

Example of a ds-example.service file:
```
### /usr/lib/systemd/system/ds-example.service
 [Unit]
 Description=Docs Example
 After=network.target syslog.target

 [Service]
 Type=simple
 User=ds
 Group=ds
 WorkingDirectory=/var/www/onlyoffice/documentserver-example
 ExecStart=/bin/sh -c 'exec /var/www/onlyoffice/documentserver-example/example 2>&1 | tee -a /var/log/onlyoffice/documentserver-xample/out.log'
 Environment=NODE_ENV=production-linux NODE_CONFIG_DIR=/etc/onlyoffice/documentserver-example NODE_DISABLE_COLORS=1

 Restart=always
 RestartSec=30

 # Give up if ping don't get an answer
 TimeoutSec=600

 [Install]
 WantedBy=multi-user.target
```
This service file provides a template for how the example server could be managed. It includes details such as the user and group the service should run under, the working directory, the execution command, and restart policies. The Environment variables are also crucial, as they configure the runtime environment for the example server.
Process Listening on examplePort: The systemd service should start a process listening on the configured examplePort (default: 3000). This is the most crucial part, as it ensures that the example server is actually running and able to accept connections.
Nginx Proxy Configuration: The Nginx upstream configuration should correctly proxy requests to the example server. This ensures that requests to /example are forwarded to the running example server process.

In essence, enabling services.onlyoffice.enableExampleServer should result in a fully functional example server, accessible via the configured port and proxied through Nginx. This includes the creation of a systemd service to manage the server's lifecycle, ensuring it's always running and accessible. Understanding this expected behavior is essential for verifying any potential fixes.

Steps to Reproduce

To reproduce this bug, follow these steps:

Build and apply the system configuration using the snippet provided earlier by running: nixos-rebuild switch

This command rebuilds the NixOS system configuration and applies the changes. It's the standard way to activate new configurations in NixOS.

Expected Outcome

The expected outcome after applying the configuration is that document editing and viewing should be available at http://localhost/example with an HTTP 200 OK status. This indicates that the example server is running correctly and accessible via the configured Nginx proxy.

Screenshots

No screenshots were provided in the original bug report.

Relevant Log Output

No specific log output was provided in the original bug report beyond the Nginx logs already discussed.

Additional Context

For comparison, the Debian package includes ds-docservice.service, ds-converter.service, ds-metrics.service, and ds-example.service. This highlights that in other distributions, the example server is treated as a separate, managed service. This comparison underscores the missing component in the NixOS module.

System Metadata

The system metadata provides valuable information about the environment where the bug was encountered:

[maksim@maksimov:~]$ nix-shell -p nix-info --run "nix-info -m"
 - system: "x86_64-linux"
 - host os: `Linux 6.12.40, NixOS, 25.05 (Warbler), 25.05.807449.ce01daebf848`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.28.4`
 - channels(root): `"nixos-25.05"`
 - nixpkgs: `/nix/store/q11ac0pfksspabwx3dshg71c9lhag2mj-nixos-25.05/nixos`

This metadata confirms that the bug was observed on an x86_64 Linux system running NixOS 25.05 (Warbler). It also provides details about the Nix version and channels being used. This information is helpful for developers attempting to reproduce the bug in a similar environment.

Notification of Maintainers

No specific maintainers were notified in the original bug report.

Importance of the Issue

The original reporter marked this issue as important, indicating that it affects their use case. This is a crucial signal for maintainers to prioritize the bug fix. Issues marked as important often have a higher impact on users and should be addressed promptly. Adding a :+1: reaction to the issue on GitHub can further emphasize its importance.

Assertion of Relevance and Conduct

The reporter correctly asserts that this issue is relevant for Nixpkgs, is a bug, and is not a duplicate. They also affirm that they have read and agree to abide by the NixOS Code of Conduct. These assertions are important for maintaining the quality and integrity of the Nixpkgs project.

Conclusion and Next Steps

Alright, guys, we've dissected this bug pretty thoroughly. The services.onlyoffice.enableExampleServer option in NixOS doesn't actually start the example server, even though it configures Nginx to proxy requests to it. This is because there's no systemd service or Nix package to run the example server. So, what's next? Well, the next step would be to actually implement the missing parts. This would involve creating a Nix package for the OnlyOffice example server and a systemd service to manage it. A pull request addressing this issue would be a fantastic contribution to the NixOS community. For those encountering this issue, a temporary workaround might involve manually setting up the example server and configuring Nginx. However, a proper fix within the NixOS module is the ideal solution. Understanding the root cause is half the battle, and now we have a clear path forward. Let's keep an eye on this and see how it gets resolved!

Repair Input Keywords

What is the bug with services.onlyoffice.enableExampleServer in NixOS?
How to configure OnlyOffice example server in NixOS?
Why does accessing http://localhost/example result in a 502 error in NixOS with OnlyOffice?
Is there a missing systemd service for OnlyOffice example server in NixOS?
How to reproduce the enableExampleServer bug in NixOS?
What is the expected behavior of services.onlyoffice.enableExampleServer in NixOS?
Why is no process listening on port 1234 when enableExampleServer is enabled?

SEO Title

OnlyOffice Example Server Bug in NixOS: A Deep Dive