Plan your installation

Read this page before you install Luvio. It explains what runs where, helps you choose an installation mode, and lists the network flows to open.

How Luvio works

flowchart TB
  client["Users' computers<br/>Luvio desktop client"]
  browser["Administrators' browsers"]
  server["Luvio server<br/>web console, API, database"]
  hv["Hypervisor<br/>Proxmox VE or VMware vSphere"]
  vm["Virtual desktops<br/>Luvio agent"]
  client -- "sign-in, pool list" --> server
  client -- "desktop stream" --> vm
  browser -- "web console" --> server
  server -- "creates and runs the machines" --> hv
  hv --- vm
  server -- "settings, commands" --> vm
  vm -- "status" --> server

• The Luvio server is the control plane. Administrators use its web console to connect hypervisors, prepare templates, create pools of virtual desktops and grant users access. It stores its data in PostgreSQL.
• The hypervisor (Proxmox VE, or VMware vSphere with vCenter) runs the virtual desktops. Luvio creates, clones, starts and deletes them through the hypervisor’s API.
• The Luvio agent runs inside each virtual desktop, Windows or Linux. It captures the screen, encodes the video and applies the user’s keyboard and mouse.
• The Luvio desktop client runs on the users’ computers. The user signs in to the Luvio server, picks a pool, and the client then connects directly to the virtual desktop for the stream.

Choose an installation mode

The Luvio server installs in four ways. They give the same product; they differ in how you run and maintain the server.

Mode	Runs on	Database	Choose it when	Guide
.deb or .rpm package	One Linux machine	Built in, managed by Luvio	You want a classic server, managed with your usual Linux tools. Simplest to operate.	Linux packages
Docker Compose	One Linux machine with Docker	A PostgreSQL 17 container	You run your services in containers.	Docker
Single Docker container	One Linux machine with Docker	Built in the container	Tests and demonstrations.	Docker
Kubernetes (Helm)	A Kubernetes cluster	A PostgreSQL 17 pod, a CloudNativePG cluster, or your own PostgreSQL	Your platform is Kubernetes.	Kubernetes

Every mode can use a PostgreSQL server of your own (PostgreSQL 12 or later) instead. With the package, you choose it in the setup wizard.

With Docker and Kubernetes, you can also give the settings of Luvio (hypervisors, administrator, directory, single sign-on) in a configuration file, kept in Git, instead of the setup wizard.

All modes install without Internet access: each release comes as packages and offline bundles that hold everything Luvio needs.

Plan for high availability

If the Luvio server stops, the users already connected keep their desktops (the stream goes directly from the desktop to the client), but nobody can sign in or open a new desktop until it is back. To avoid this, run several Luvio servers on one highly available database:

Mode	High availability
Kubernetes (Helm)	Supported: several pods, on a CloudNativePG cluster or your own highly available PostgreSQL
Docker	Supported with application nodes: two or three Docker hosts, on your own highly available PostgreSQL, behind a virtual IP address or your load balancer
.deb or .rpm package	One server. Its database can be your own highly available PostgreSQL

See High availability. With one server, back up its database and its keys (each guide explains how).

Sizing

Luvio server. Start with 2 vCPU, 4 GB of RAM and 40 GB of disk: this is what the guides were validated on. The server does not carry the video streams, so its load grows with the number of machines it manages and of users who sign in, not with the screen activity.

Universal Templates (copying a template from one hypervisor to another, optional) needs working space on the server: the size of the data of the template, plus 10% per disk, plus 1 GB. On vSphere, count the largest disk twice. A 60 GB Windows template needs about 70 GB.

Virtual desktops. Size them for their operating system and their users’ applications, plus the agent’s video encoding: give Windows desktops at least 2 vCPU and 6 GB of RAM (Luvio requires 6 GB for a Windows template), Linux desktops 2 vCPU and 4 GB.

Network. A desktop stream uses up to 80 Mbit/s at its best quality, much less on a still screen.

Network flows

Open these flows in the firewalls between the zones. The ports are the defaults.

From	To	Port	Use	Needed
Administrators’ browsers	Luvio server	TCP 3080 (HTTP) or 3443 (HTTPS)	Web console	Always
Users’ computers	Luvio server	TCP 3080 or 3443	Sign-in, pool list, connection tickets	Always
Users’ computers	Virtual desktops	TCP 8081	Opening a session on the desktop	Always
Users’ computers	Virtual desktops	UDP 4433	Desktop stream (QUIC)	Always
Virtual desktops (agent)	Luvio server	TCP 3080 or 3443	Status reports of the agent	Always
Luvio server	Virtual desktops (agent)	TCP 8081	Settings, commands, template preparation	Always
Luvio server	Proxmox VE nodes	TCP 8006	Proxmox API, machine consoles (Luvio relays them to the browser)	Proxmox
Luvio server	vCenter Server	TCP 443	vSphere API, ISO uploads	vSphere
Luvio server	ESXi hosts	TCP 443	Machine consoles (Luvio relays them to the browser)	vSphere
Luvio server	Proxmox VE nodes	TCP 22	Universal Templates (SSH)	Optional
Luvio server	LDAP or Active Directory	TCP 636 (LDAPS) or 389 (StartTLS)	Directory accounts	Optional
Luvio server	Identity provider	TCP 443	OpenID Connect sign-in	Optional

Things to know:

• Users’ computers must reach the virtual desktops directly, on TCP 8081 and UDP 4433. Luvio has no gateway that relays the streams. Users outside your network connect through a VPN that routes them to the desktops’ network.
• The server tells the agents which address and port to use: the Server URL of the web console and the port Luvio listens on. The .deb or .rpm package listens on both ports and the agents use HTTPS (3443); Docker and Kubernetes listen on HTTP (3080) unless you enable HTTPS. With Docker and Kubernetes, you give that address at installation: inside a container, Luvio cannot see the address the virtual machines reach. A load balancer or a NAT in front of Luvio must publish the same port number (3080 or 3443).
• Synchronize every clock with NTP: server, hypervisors and desktops. The messages between the agents and the server are refused beyond 5 minutes of difference.
• With several Luvio servers (high availability), open the flows of the Luvio server for each of them: each one connects to the hypervisors and to the agents from its own address. The agents and the users reach them through one address (a Kubernetes Service, a virtual IP address or a load balancer). Keepalived needs VRRP (IP protocol 112) between the Docker hosts.
• Universal Templates on Proxmox VE sign in to the nodes over SSH only once an administrator has trusted the SSH host key of each node: the check in the hypervisor’s settings shows its fingerprint, to compare with the one ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub prints in the node’s Shell before you trust it. Give Luvio a dedicated SSH account with a private key rather than the password of root@pam (see Universal Templates).
• The Luvio server makes no call to the Internet, except when an administrator asks it to download the latest VirtIO drivers for Windows on Proxmox.
• The agent opens its ports in the desktop’s firewall itself on Windows and on Linux with firewalld. On a Linux desktop with ufw, open them in the template (see Templates, agent and pools).

Before you start

• A machine (or a cluster) for the Luvio server, sized as above, with a fixed address or DNS name.
• The release files from <DOWNLOAD_URL>: the server package or bundle, the agent ISO for each desktop operating system, the desktop client installers.
• An account on the hypervisor: root@pam on Proxmox VE, or a vCenter account with the privileges listed in the VMware vSphere setup guide.
• The installation ISO of the desktop operating system, on the hypervisor’s ISO storage.
• The network flows above opened.
• NTP on every machine.

Then install the server: Linux packages, Docker or Kubernetes.