Ubuntu server installation (native, no Docker)
The recommended way to run YARMA on your own server: one Ubuntu 24.04 machine (VM, bare
metal or LXC container), no Docker, behind your existing HTTPS reverse proxy such as Nginx
Proxy Manager. Everything runs as system services and upgrades in place. The installer is
install.sh in the server bundle.
What it installs (Ubuntu 24.04)
| Component | Bound to | Notes |
|---|---|---|
nginx: console + /api proxy |
0.0.0.0:18080 |
point the reverse proxy host here |
| yarma-api: API | 0.0.0.0:10443 |
TLS with an internal CA; reached through nginx (also listens on the LAN, authenticated) |
| yarma-api: agent service | 0.0.0.0:18443 |
mutual TLS; forward TCP from the internet (NPM "Stream"), never terminate TLS |
| coturn | 3478 udp/tcp, relay 49160-49200/udp |
forward from the internet; set --turn-ip behind NAT |
| PostgreSQL | 127.0.0.1:5432 | TLS (ssl_mode: require), password auth |
| Redis, NATS JetStream, SeaweedFS S3 | loopback | passwords / credentials generated |
| ClamAV | 127.0.0.1:3310 | only with --clamav (needs ~1.5 GB RAM, up to ~2.5 GB while signatures reload); without it file transfers are not malware-scanned |
Paths: binaries and console /opt/yarma-cloud, configuration /etc/yarma-cloud
(config.yaml, api.env 0600, TLS, keys, agent PKI), data /var/lib/yarma-cloud, backups
daily to /var/backups/yarma-cloud (14 days). Services: yarma-api, yarma-nats,
yarma-seaweedfs, coturn, redis-server, postgresql, nginx.
Install or upgrade
Download yarma-server-native-<version>-linux-amd64.tar.gz from the
download page (or build it with
scripts/package-native.sh), unpack it and run:
sudo ./install.sh --domain yarma.example.com --trusted-proxy <proxy IP>/32 [--clamav] [--turn-ip <public IP>]
The bundle contains the server, the console, SeaweedFS, the agent packages, the License
Center address and its public key; --license-center URL and --license-pub FILE override
the last two (e.g. for your own License Center).
Re-running with a new bundle upgrades binaries, console and agent packages and runs migrations; settings, keys and data are kept. These options also apply on upgrade:
| Option | Effect |
|---|---|
--clamav |
installs ClamAV, waits for its signatures, raises its size limits to the 100 MB transfer limit and turns on scanning (files.clamd_addr) |
--turn-ip PUBLIC[/PRIVATE] |
coturn external-ip behind NAT (e.g. 203.0.113.7/10.0.10.70) |
--agent-host HOST |
devices connect to https://HOST:18443 (agents.public_url); the agent-service certificate is reissued from the same CA to include HOST, so enrolled devices keep working |
--turn-host HOST |
name in the TURN URLs given to browsers and agents |
--server-token yls_… |
registers the server with the License Center (operator console → Infrastructure → Cloud servers → Register): it reports health and usage every 5 minutes and sets up customers' organizations automatically. Only for the License Center operator's own servers |
Behind Cloudflare (orange-cloud proxy on the console name): Cloudflare carries HTTPS to the
console, but not the agents' mutual TLS on 18443 nor TURN. Create DNS-only (grey-cloud)
records pointing at the server's public IP, e.g. agents.example.com and turn.example.com,
and pass them with --agent-host and --turn-host.
The agent-service certificate can also be reissued by hand (new name, or before it expires
after two years): sudo /opt/yarma-cloud/bin/yarma-api -config-dir /nonexistent pki server -dir /etc/yarma-cloud/pki -hosts cloud.example.com,agents.example.com, then restart yarma-api.
Agent packages
Put the agent packages of a release into the bundle's agent/ directory (the
yarma-agent* .msi, .pkg, .deb and .rpm files and a VERSION file with the version). The
installer publishes them in /opt/yarma-cloud/downloads (agents.downloads_dir), where
Settings → Enrollment offers them and the one-line install commands fetch them
(agents).
Administration
sudo yarma-cloud-admin bootstrap -tenant <slug> -name '<Name>' -admin-email <email> (set
YARMA_BOOTSTRAP_ADMIN_PASSWORD to choose the password), … license install -tenant <slug> -file <license>, … verify, … migrate status.
Reverse proxy (Nginx Proxy Manager)
| Host | Forward to | Options |
|---|---|---|
console host, e.g. cloud.example.com |
http://<server>:18080 |
Let's Encrypt, Force SSL, HTTP/2, HSTS, WebSockets on (remote sessions and terminal use them) |
| Stream: TCP 18443 | <server>:18443 |
agents; TCP pass-through |
| TURN | router port forwards for 3478 udp/tcp and 49160-49200/udp | NPM streams can carry 3478 but not the relay range conveniently |
Documentation for Yarma 0.1.0-alpha.4. Something unclear? .