Skip to content
Virtainer Docs Virtainer Docs Virtainer Docs

Install Virtainer Lite

Updated

Virtainer Lite ships as a single self-contained appliance image. You install it by booting the target host from a Fedora LiveCD and writing that image directly to the host’s disk. The install itself is one podman command that you run from the live environment.

System requirements

Section titled “System requirements”

Check these before you go any further. The install erases a disk, so it is not something to discover halfway through.

RequirementDetail
Architecturex86_64 (amd64). There is no build for other architectures
VirtualizationHardware virtualization enabled in firmware (Intel VT-x or AMD-V). Every machine on the host runs on KVM, so a host without it cannot run anything
A disk to eraseThe install takes a whole disk. It does not resize or dual-boot
NetworkA wired interface, and internet access from the live environment
IOMMUOnly for PCI passthrough. Enable it in firmware now if you plan to pass hardware through later, so you do not reinstall to get it

The appliance brings its own operating system, so nothing needs to be installed on the host beforehand.

Before you begin

Section titled “Before you begin”
  • A host you can boot from a Fedora LiveCD, ideally the latest stable release. Two things make it the supported medium rather than a preference: it ships podman, which the installer runs from, and it names network interfaces the same way the installed host will, so the interface name you read during the install is the one the host actually uses afterwards.
  • Internet access from the live environment. The installer pulls the Virtainer Lite image from quay.io during the install, so the host must be online.
  • The target disk for the install. The examples below use /dev/sda; replace it with the correct device for your host.
  • The network setup the host should use: DHCP, or a static address with its gateway, netmask, and interface name.

Install

Section titled “Install”

  1. Boot the host from a Fedora LiveCD.

    Working from the live environment also lets you read the host’s real disk and network interface names before you install. Both vary from machine to machine, and you need them in the steps below. The interface name you read here is the one the installed host will use, which is why a different live medium can leave you with a static address configured on a name that does not exist after the reboot.

    Optional: on a host with less than 12 GB of RAM, give the live environment a larger writable overlay so the installer has room to work. Append this to the kernel command line in GRUB before booting:

    GRUB kernel command line
    rd.live.overlay.size=12G

  2. Put SELinux into permissive mode for the install session:

    Terminal window
    sudo setenforce 0

  3. Write Virtainer Lite to the disk.

    Run the installer from the live environment. Pick the tab that matches how the host should get its network address, and replace /dev/sda with your target disk.

    Terminal window
    sudo podman run --rm \
      --privileged \
      --pid=host \
      --ipc=host \
      --security-opt label=disable \
      -v /dev:/dev \
      quay.io/virtainer/lite:latest \
      bootc install to-disk \
      --source-imgref registry:quay.io/virtainer/lite:latest \
      --wipe \
      --block-setup=direct \
      --disable-selinux \
      --filesystem=xfs \
      --bootloader=grub \
      --karg=ignition.firstboot=1 \
      --karg=ignition.platform.id=metal \
      --karg=rd.neednet=1 \
      --karg=ip=dhcp \
      /dev/sda

  4. Reboot the host and remove the live media. The host boots from disk into Virtainer Lite.

Access Virtainer Lite

Section titled “Access Virtainer Lite”

Once the host has rebooted, open Virtainer Lite in a browser at http://<host-ip>. The web UI is served on the default HTTP port, so the address needs no port number. Use the address the host has on your network: its DHCP lease, or the static address you set during install (for the example above, that is http://192.168.50.100).

  • First visit: complete the one-time initialization to set up Virtainer Lite.
  • After initialization: open the same URL for day-to-day operation, such as creating and managing VMs and AppVMs.

If you cannot reach the host

Section titled “If you cannot reach the host”

The host answers on the address it holds on your network. When the page does not load, work through these in order.

  1. Find the address it actually got.

    Log in at the host’s own console, on the monitor and keyboard attached to the machine, and run:

    Terminal window
    ip -brief address

    That prints each interface with the address it holds. If you installed with DHCP, look for the lease your server handed out. Your DHCP server’s lease table works too.

  2. Check the interface name was right.

    A static install writes the address to one named interface. If you guessed the name during the install, the address went to an interface that may not be the one plugged in. ip -brief link shows which interfaces exist and which are UP.

  3. Confirm the host booted from disk.

    If the machine booted the live media again, remove it and reboot.

  4. Reinstall if the address is wrong.

    The install is one command and the disk is already dedicated to it, so correcting an interface name or address is faster than repairing it in place.

Next

Section titled “Next”

The first visit walks you through a setup wizard and ends with a host reboot. First-run setup covers what it asks for and what to watch out for at the storage step.