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:
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 bypassingufw's rules: whatever you publish without127.0.0.1:is open to the internet, whateverufwsays. - At home, remove
127.0.0.1:from the three lines (or use"4890-4892:4890-4892"): on your network, the Library is athttp://MACHINE-IP:4891and Files at:4892. - If a port is taken, use another on both sides, with its variable in
.env:KUMOYAMI_LIBRARY_PORT=5891and"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):
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=4892Then 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 tcpThe 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:
app.example.com, drive.example.com {
reverse_proxy 127.0.0.1:4890
}And reload:
sudo systemctl reload caddyIf 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
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 nginxOn 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.comCertbot 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
- Your own domain: what's on each port and which way to pick.
- Without opening ports, if the server has no public IP.
- Nginx Proxy Manager and Traefik, if you already use them.
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.