Skip to content

Docker and Linux

Caddy or Nginx in front of KumoYami on a Linux server or with Docker, with both addresses and a Let's Encrypt certificate.

On a Linux server, a VPS or any machine with Docker, put a reverse proxy in front of port 4890. Here are the two most common ones, Caddy and Nginx, with the example's two addresses: the Library on app.example.com and Files on drive.example.com.

First, create both DNS records (type A with the server's public IP) and open 80 and 443 to it.

If you installed with install.sh

The installer sets up Caddy for you with --domain and --library-domain: see Caddy. This page is for doing it by hand or with your own proxy.

Publish the three ports

In docker-compose.yml, the web service publishes the launcher and the panel (4890), the Library (4891) and Files (4892). The one from kumoyami.com/install already has all three, on the machine itself only:

docker-compose.yml
services:
  web:
    # … (image, volumes and the rest, as they were)
    ports:
      - "127.0.0.1:${KUMOYAMI_PORT:-4890}:4890"
      - "127.0.0.1:4891:4891"
      - "127.0.0.1:4892:4892"

If your file is older and only has the 4890 line, add the other two and apply the change:

sudo docker compose up -d
  • On a server with a public IP, leave them like that, with 127.0.0.1: in front, and come in through the proxy. Docker publishes ports bypassing ufw's rules: whatever you publish without 127.0.0.1: is open to the internet, whatever ufw says.
  • At home, remove 127.0.0.1: from the three lines (or use "4890-4892:4890-4892"): on your network, the Library is at http://MACHINE-IP:4891 and Files at :4892.
  • If a port is taken, use another on both sides, with its variable in .env: KUMOYAMI_LIBRARY_PORT=5891 and "127.0.0.1:5891:5891". The launcher links to each module by its port, so the outside and inside numbers have to match.

Without Docker: the .deb package

With the .deb package, the three ports open on their own, on every address of the machine. /etc/default/kumoyami only ships PORT=4890 (and HOSTNAME), but the service reads the whole file: add the modules' ports there if you want to change them (0 leaves the module without a port of its own):

/etc/default/kumoyami
PORT=4890
# HOSTNAME=127.0.0.1 keeps the three ports on the machine itself, behind the proxy
HOSTNAME=0.0.0.0
KUMOYAMI_LIBRARY_PORT=4891
KUMOYAMI_FILES_PORT=4892

Then restart with sudo systemctl restart kumoyami. The package doesn't touch the firewall: with ufw on, open the three ports to your local network only (change the network to yours), or don't open them if you come in through the proxy:

sudo ufw allow from 192.168.1.0/24 to any port 4890:4892 proto tcp

The proxy always points at 4890, for the Library and Files too: KumoYami picks the module by the name the request arrives with (how it picks it).

Caddy

Caddy gets and renews the certificates on its own, and passes on the original name, WebSockets and the X-Forwarded-* headers without being told. With Caddy installed on the server, add this to your Caddyfile:

/etc/caddy/Caddyfile
app.example.com, drive.example.com {
	reverse_proxy 127.0.0.1:4890
}

And reload:

sudo systemctl reload caddy

If Caddy runs in a container in the same docker-compose.yml, the target is web:4890. Nothing else is needed, not even for large uploads or the network drive (WebDAV).

Nginx

Nginx has to be told everything: the original name (Host), WebSockets (Upgrade and Connection), the visitor's IP and protocol (X-Forwarded-*) and to accept large uploads.

Create the site

/etc/nginx/sites-available/kumoyami
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name app.example.com drive.example.com;

    # Uploads of any size, the network drive (WebDAV) included
    client_max_body_size 0;
    proxy_request_buffering off;

    location / {
        proxy_pass http://127.0.0.1:4890;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_read_timeout 1h;
    }
}

Enable it and check the configuration:

sudo ln -s /etc/nginx/sites-available/kumoyami /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

On distributions without sites-available (Rocky, Alma, Fedora), save the file as /etc/nginx/conf.d/kumoyami.conf. If nginx -t says $connection_upgrade is a duplicate, another site already has that map: remove it from this file.

Get the certificate

sudo certbot --nginx -d app.example.com -d drive.example.com

Certbot adds the listen 443 ssl, the certificate for both names and the HTTP-to-HTTPS redirect, and schedules the renewal. It needs port 80 to reach the server.

More details, such as a separate location for /webdav/, in Nginx.

Save the addresses

In the panel, System → Modules: https://app.example.com for the Library and https://drive.example.com for Files. Save both and open them.

If something goes wrong

502 Bad Gateway

The proxy can't reach KumoYami. See whether the container is running (sudo docker compose ps) and 4890 is published: curl -I http://127.0.0.1:4890 should answer. From another container, the target is web:4890, not 127.0.0.1.

WebSocket errors or "connection lost"

Nginx is missing proxy_http_version 1.1 and the example's Upgrade and Connection headers. Caddy needs nothing.

Certificate error

If certbot or Caddy can't get the certificate, DNS doesn't point at the server yet (dig +short app.example.com) or port 80 is closed in the firewall or your provider's. With Caddy, sudo journalctl -u caddy says why.

"413 Request Entity Too Large"

By default Nginx cuts requests over 1 MB: client_max_body_size 0; is missing.

The launcher, the other module or "nothing published" shows up

  • Files on the Library's address: an unsaved domain shows Files. Save the Library's address in System → Modules, or the proxy isn't passing on the original name: in Nginx, proxy_set_header Host $host.
  • The launcher: you're coming in by IP or by an address with a port (:4890, :8443) that isn't saved.
  • "Nothing published": that module is turned off in System → Modules.

Every case, in How KumoYami picks the module.

Next steps

All trademarks and logos belong to their respective owners. Their use only indicates compatibility, not sponsorship or affiliation. The Synology logo is a trademark of Synology Inc.; Google Drive, Google Cast and Android are trademarks of Google LLC, and the Android robot is reproduced from work created and shared by Google, used under the Creative Commons Attribution 3.0 license. Microsoft, Windows and OneDrive are trademarks of the Microsoft group of companies; Amazon S3 is a trademark of Amazon.com, Inc. or its affiliates; Apple, AirPlay, macOS and iPhone are trademarks of Apple Inc.; Raspberry Pi is a trademark of Raspberry Pi Ltd; Ubuntu is a trademark of Canonical Ltd.; Debian is a trademark of Software in the Public Interest, Inc.; Linux is a trademark of Linus Torvalds. This product uses the TMDB API but is not endorsed or certified by TMDB.