cells_proxy_nginx.md

In this tutorial, we explain how to use nginx as reverse proxy in front of a Pydio Cells instance, together with a few tips to address the most common issues.

Requirements

We assume that:

• You are using a Linux server, if not you might have to adapt some commands
• You own a FQDN (e.g.: cells.example.com) that has been registered in a public DNS
• Your A record has been propagated: you can verify this with ping <YOUR_FQDN> from your local workstation
• Both port 80 and 443 are free and not blocked by any firewall sudo netstat -tulpn

Depending on your setup, you might have to install nginx on your machine, please refer to the official documentation.

You also must adapt your configuration to define your public FQDN, and optionally adapt bindind configuration. To do so, you have 3 options:

• Open a shell on the machine where the application is running and call the cells configure sites command, with the user that runs the service
• Define CELLS_SITE_EXTERNAL (and optionally CELLS_SITE_BIND and CELLS_SITE_NO_TLS) environment variable or the corresponding flag
• Add a proxyconfig section in your YAML installation file (or ProxyConfig if you use JSON format)

Note that the external (public) URL must contain the protocol (http or https).

Examples

Simple setup on a stand alone server

We assume that:

• your registered FQDN is cells.example.com, adapt with your FQDN
• nginx and cells are running on the same machine
• you have docker installed and have launched a Collabora server with e.g.: docker run -t -d --restart=always -p 9980:9980 -e "domain=cells.example.com" collabora/code
• you have used Certbot to generate the certificates

This config has been last tested with nginx version 1.18 that can be installed on Debian 11 (Bulleyes) by running sudo apt install nginx.

server {
    server_name cells.example.com;
    
    # Allow any size file to be uploaded
    client_max_body_size 0;
    # Disable buffering
    proxy_buffering off;

    # Main entry point for the application
    location / {
        # Uncomment this to enable gRPC and thus be able to use cells-sync
        #if ($http_content_type = "application/grpc") {
        #    grpc_pass grpcs://cells:8080;
        #}
        proxy_pass https://localhost:8080;
    }

    # Enable the websocket
    location /ws/ {
        proxy_pass https://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

   # Necessary to use Collabora (online edition of office documents)
   location /cool/ {
        proxy_pass https://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

    error_log /var/log/nginx/cells-proxy-error.log;
    access_log /var/log/nginx/cells-proxy-access.log;

    listen [::]:443 ssl;
    listen 443 ssl http2;
    
    # certificate configuration (generated by certbot)  
    ssl_certificate /etc/letsencrypt/live/cells.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cells.example.com/privkey.pem;
}

server {
    if ($host = cells.example.com) {
        return 301 https://$host$request_uri;
    }

    listen 80;
    listen [::]:80;
    server_name cells.example.com;
    return 404;
}

Further configuration

Cells Sync

Cells Sync is the desktop client tool that can be used to synchronise a folder on your local workstation with e.g. a subfolder of your personal file folder on the server.

In Cells Home distribution, you can only use the Cells Sync client with sub-folders of the Personal Files workspace (a.k.a: My Files).

The communication between the client and the server uses gRPC on http2, thus:

• HTTP2 has to be enabled on nginx with http2 for instance listen 443 ssl http2;
• if you are using TLS encryption, you cannot perform TLS termination at the reverse proxy (nginx) level

Collabora

With the setup described above, you must also configure the Collabora plugin via the Cells Admin Console:

• Go to Admin Console >> Advanced Parameters >> Application Parameters >> All Plugins >> (search for collabora)
• Enable the plugin
• Configure with:
  • Code version: 21 and upper
  • Libre Office SSL: enabled
  • Host for Libre Office: localhost
  • Port: 9980
• It is safer to restart the Cells service

---

See Also

Running Cells Behind a reverse proxy