Introduction
What you need to install KumoYami, and where to start for your kind of machine.
KumoYami is a file website you install on your own server. It brings OneDrive, your server's folders and the rest of
your storage together in one index, with viewers, a media player, share links and upload boxes. It runs on
Docker, in a single container, and you set it up from its admin panel at /admin.
This guide covers installing it on each kind of machine, putting it on your domain with HTTPS, the first-run setup and day-to-day upkeep (updating, backups, moving to another server).
What you need
- Your license. When you buy, you get an email with its ID (
lic_followed by 12 characters) and its key (starting withKY1.). They let you download the private image fromregistry.kumoyami.comand activate the admin panel. - A machine with Docker and Docker Compose. A Linux server or VPS is the easiest option: the installer adds Docker if it's missing. A NAS (Synology, QNAP, Unraid, TrueNAS) or a computer with Docker Desktop works too.
- An x86_64 processor (Intel or AMD). For ARM processors, read Raspberry Pi and ARM.
- Outbound internet access. The server pulls the image from
registry.kumoyami.comand checks in withlicencias.kumoyami.comonce a day to renew the license (over HTTPS, port 443). - A domain with HTTPS (recommended). The machine's IP is enough for use at home, but to share links, connect OneDrive from outside or use passkeys you need a domain with a certificate. See Domain and HTTPS.
Resources
| Minimum | Recommended | |
|---|---|---|
| Memory | 1 GB of RAM | 2 GB (4 GB if you enable the ClamAV antivirus) |
| Disk | 5 GB free for Docker and the image | Plus whatever your local files take up |
Files on OneDrive and other cloud storage are never copied to the server: KumoYami reads them on the fly.
Your site keeps working offline
The license is checked once a day and stays valid for 14 days without reaching the license server. If it ever lapsed, only the admin panel would be locked: your visitors wouldn't notice a thing.
Choose how to install
Quick install
One command on a Linux server: Docker, your license, HTTPS with Caddy and first start.
Docker Compose by hand
On any system with Docker, step by step, without the installer.
Synology
In Container Manager, as a Compose project.
QNAP
In Container Station, as a Compose application.
Unraid
With the Compose Manager plugin or from the terminal.
TrueNAS SCALE
As a custom app from a Compose file.
Windows and macOS
With Docker Desktop, to try it out or use it at home.
Raspberry Pi and ARM
Raspberry Pi, servers and NAS with ARM processors.
How it fits together
Browser
│ HTTPS (ports 80 and 443)
▼
Reverse proxy: Caddy, Nginx…
│
▼
KumoYami on 127.0.0.1:4890
├──▶ OneDrive, server folders, other clouds…
└──▶ datos/ (settings, tokens, license)KumoYami only listens on the server itself, on port 4890. A reverse proxy sits in front and handles the domain and
HTTPS (the installer can set up Caddy for you). Everything you configure in the panel is saved in the datos/ folder,
next to docker-compose.yml and .env: those three are what your backups need.
Port 4890
You can change it with KUMOYAMI_PORT in .env (for example KUMOYAMI_PORT=8080) followed by
docker compose up -d. Installs made before this change listen on 3000: check the ports line in your
docker-compose.yml to see which one yours uses.