Install from the OVA

The .ova is the complete ONEP appliance. You import it, turn on nested virtualization, and start it. The steps are the same idea on every hypervisor: import, set CPU, memory and network, start, then sign in from your browser.

Pre-flight checks#

Check these before you import.

• Hardware virtualization: the host CPU supports Intel VT-x or AMD-V, and it is enabled in the firmware.
• Nested virtualization: your hypervisor can pass hardware virtualization through to a guest. Without it, virtual machine devices do not start. Routers and containers do. The console banner and Settings › Status tell you when it is missing.
• Memory: 8 GB for the appliance at minimum (small environments), 16 GB recommended (3 or 4 virtual machines), 32 GB for large environments.
• CPU: at least 4 vCPU.
• Disk: the appliance has a 200 GB virtual disk, thin-provisioned, so it takes space on the host only as it fills. Images and environments live on it.
• Network: one interface on a LAN your browser can reach, with DHCP for the first boot.

Proxmox VE#

1. Copy and unpack the applianceCopy the .ova to the Proxmox VE host and unpack it; an .ova is a tar archive holding an .ovf description and the disk.

   mkdir -p /root/onep-import && cd /root/onep-import
   tar -xvf /path/to/onep-appliance.ova

2. Import it as a virtual machinePick a free virtual machine ID (300 here) and the storage for the disk (local-lvm here).

   qm importovf 300 /root/onep-import/*.ovf local-lvm

   Newer Proxmox VE versions can also import an .ova from the web interface, on a storage that allows import content.
3. Set CPU type host, memory and networkThe CPU type must be host so the appliance gets nested virtualization. Give it a network card on a bridge that reaches your LAN. Do this before you start it.

   qm set 300 --cpu host --cores 4 --memory 16384
   qm set 300 --net0 virtio,bridge=vmbr0
   qm set 300 --name onep

4. Optional: give the disk more roomIn the Proxmox VE interface, Hardware › Hard Disk › Disk Action › Resize. See Growing the disk.
5. Start itand open the virtual machine's console. Continue with First start.

The commands are Proxmox VE's own; the file names are examples.

VMware Workstation#

1. ImportChoose File › Open, select the .ova, name the virtual machine, choose a folder and choose Import. Do not power it on yet.
2. Enable hardware-assisted virtualizationOpen VM › Settings › Processors, give it at least 4 cores, and tick Virtualize Intel VT-x/EPT or AMD-V/RVI. Do this before you power it on.
3. MemoryAt least 8 GB; 16 GB recommended.
4. Network AdapterBridged puts the appliance on your LAN; NAT keeps it reachable from this host only.
5. Optional: Hard Disk › Expandto give the disk more room.
6. Power onand watch the console. Continue with First start.

If Workstation will not power on with virtualization ticked, another hypervisor on the host may be holding VT-x or AMD-V. Your host's own virtualization settings decide this.

VirtualBox#

1. ImportChoose File › Import Appliance, select the .ova, review the settings and choose Finish. Do not start it yet.
2. Enable nested virtualizationOpen Settings › System › Processor, give it at least 4 processors, and tick Enable Nested VT-x/AMD-V. If the box is grayed out, close VirtualBox and run this once, then open it again:

   VBoxManage modifyvm "ONEP" --nested-hw-virt on

   Do this before you start it.
3. MemoryAt least 8 GB; 16 GB recommended, under Settings › System › Motherboard.
4. NetworkUnder Settings › Network, set Adapter 1 to Bridged Adapter on the interface that reaches your LAN. NAT keeps the appliance reachable from this computer only.
5. Optional: give the disk more roomVirtualBox enlarges VDI disks in File › Tools › Virtual Media Manager. The imported disk is a VMDK, so convert it first:

   VBoxManage clonemedium disk onep-disk1.vmdk onep-disk1.vdi --format VDI
   VBoxManage modifymedium disk onep-disk1.vdi --resize 400000

   then attach the new disk in place of the old one. See Growing the disk.
6. Startand watch the console. Continue with First start.

On a Windows computer, Hyper-V, Windows Subsystem for Linux 2, or Virtualization-based security can hold the hardware virtualization that VirtualBox needs for the nested setting; VirtualBox then runs slowly and virtual machine devices do not start. Turn those Windows features off, or run the appliance on VMware Workstation or a Proxmox VE server instead.

First start#

1. Wait for the platformThe console shows the ONEP banner above the operating system's login prompt. It shows the edition, version and build, a Status line, and the address to open. The Status line reads Platform ready when the platform is up. The address line refreshes every five minutes, so it follows a DHCP change. You do not need the console login.
2. Open the addresshttps://<address>/ in a browser. The certificate warning is expected: the appliance created its own certificate on first boot.
3. Create the administrator passwordThe first time you open the address, ONEP shows Create the administrator password before anything else. Type a password of at least 12 characters, type it again, and choose Create and sign in. ONEP does not generate a password: nothing is shown on the console and nothing is written to a file. Until the password exists, whoever opens the address first can create it, so do this step yourself right after the appliance starts.
4. Complete the first-time setupONEP then opens the first-time setup: Agreement, License, Network, ONEP Assistant and Ready. You must accept the agreement. You can skip License, Network and ONEP Assistant and set them later in Settings.

The account is admin; sign in with it, and the password you created, from then on. Continue with First boot and network and After install. Shut the virtual machine down with the hypervisor's shutdown, not a power-off. The appliance stops its running virtual machines and its services first.

Growing the disk#

Images and environments live on the appliance's disk. If you need more room, enlarge the virtual disk in your hypervisor, before or after the first boot. On its next boot the appliance grows its file system to use the new space automatically; there is nothing to do inside the appliance.

Check it worked#

After you have created the administrator password, from a machine that can reach the appliance:

curl -sk https://<address>/api/system/version
curl -sk https://<address>/api/system/edition

The first returns the product, the version, the build and the edition. The second shows the edition and "runtime_enabled":true. In the web interface, Settings › Status shows Virtualization: Ready when nested virtualization works.

If something goes wrong#

More in Troubleshooting.