Running Cells behind a Nginx reverse proxy

Created on 2021/11/12, cells, configuration, grpc, nginx, reverse-proxy, Sync
Category: 

In this tutorial, we explain how to use nginx as reverse proxy in front of a Pydio Cells instance.
We present a basic setup and give a few tips to address the most common issues.

Adapt Cells configuration

By default, Cells starts on port 8080 with a self-signed certificate. To adapt your configuration, you have 3 options:

  • open a shell on the same machine where the service is running and call the cells configure sites command
  • define (at least) the CELLS_BIND and CELLS_EXTERNAL environment variables or the corresponding flags (see the help for other flags, typically to choose http or https between nginx and Cells)
  • add a proxyconfig section in your YAML installation file (or ProxyConfig if you use JSON format)

Doing so, you can define:

  • Bind Address: interface and port used to bind Cells on the server.
  • External URL: the public URL that you communicate to your end users. Note that the external URL must contain the protocol (http or https).

Basic NGINX reverse proxy configuration

To have the latest nginx version follow the official nginx documentation (https://nginx.org/en/linux_packages.html).

Then edit the configuration file to have (replace dummy place holder with your specific info):

server {
    server_name cells.example.com;

    # Allow any size file to be uploaded.
    client_max_body_size 0;
    # To disable buffering
    proxy_buffering off;

    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://cells:8080;
    }


    location /ws/ {
        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 (in this case generated by certbot)
    ssl_certificate /etc/letsencrypt/live/my-cells-server.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/my-cells-server.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

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

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

This config has been last tested and updated with version: nginx/1.20.0.

Cells Sync

Mandatory section for the Sync Client to work behind a nginx reverse proxy.

If your Cells Server is running behind a nginx reverse proxy you must meet at least the following requirements.

  • TLS encryption between Cells and nginx.
  • HTTP 2 has to be enabled on nginx with http2 for instance listen 443 ssl http2;.

Finale note

Make sure to substitute the values of the certificates and ip/domains.


See Also

Running Cells Behind a reverse proxy