UserVM Handbook/Windows

This guide details how to set up a UserVM on a host machine running Microsoft Windows.

The Rules

First, the boring part. We ask that all hosts review and follow the UserVM Hosting Rules.

Prerequisites

You'll need:

  • A machine with decent specs (8GB of RAM and a modern CPU, probably)
  • Microsoft Windows 10 or later. For Linux, see the main UserVM Handbook.
  • A decently fast network that allows you to forward a port. We will not accept UserVMs behind services like ngrok. Cloudflare tunnels are fine. You must also have a URL that stays persistent. If your IP is dynamic, you can use services like NOIP or setup a script to auto-update your domain using cloudflare.
  • Basic knowledge of how computers and Windows systems work. We aren't going to hold your hand, you need to be comfortable with a command line
  • A few hours

Compiling the server

Install dependencies

Open Command Prompt as administrator.

First, install the Chocolatey package manager. If you already have it installed, you can skip this step.

powershell -c "Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))"

Restart CMD to apply the changes to PATH. Now, we'll install the various dependencies CollabVM has:

choco install qemu git nasm cmake nodejs nssm rust-ms visualstudio2019-workload-vctools
refreshenv

Enable corepack:

corepack enable

Prepare the server

We can now get the server ready. First, create a directory for all CollabVM related files. For the purposes of this guide, we use C:\collabvm. If you use a different directory, be sure to substitute it in all future commands.

mkdir C:\collabvm

Clone the CollabVM server source:

git clone https://github.com/computernewb/collabvm-1.2.ts.git C:\collabvm\collabvm-1.2.ts --depth 1 --recursive
cd C:\collabvm\collabvm-1.2.ts

Install dependencies and build the server:

yarn
yarn build

Set up your VM

Now is a good time to get your VM set up. Currently, the only supported hypervisor is QEMU. We have many guides on this wiki for setting up different OSes in QEMU, check them out here. Here are some ideas to make your VM interesting:

  • A funny wallpaper
  • Development software (Visual Studio, etc.)
  • Some games
  • Some harmless malware (for the love of god no GDI rapists)

Windows Hypervisor Support

By default, QEMU uses the TCG software emulator, which is very slow. You can greatly increase the speed of your VM by enabling Windows Hypervisor.

First, enable the Windows Hypervisor:

dism /online /enable-feature /featurename:HypervisorPlatform

Reboot your system to apply changes

Now, you can enable WHPX hypervision by using the -accel whpx argument somewhere in your QEMU command line. If you're copying your QEMU command from somewhere that expects KVM (which is the Linux equivalent to the Windows Hypervisor), make sure you REPLACE the -accel kvm with -accel whpx in the command or it will not run.

Note that there is also a fork of QEMU that uses the Android Emulator Hypervisor Driver, which may be faster than the Windows Hypervisor but is also known to be very buggy.

Setting up a Virtual Network

TODO: Windows version of CollabNet Guide host shit using OpenVPN wintun bullshit (pain)

Configuration

Now we need to fill out the config file for your VM. Copy config.example.toml to config.toml, and open it in an editor. It is well commented so each value should be self-explanatory. If you have questions, feel free to ask in our Discord server.

QEMU Args

On Windows, if QEMU is installed to the default directory, you'll need to configure your qemuArgs like this:

qemuArgs = "C:\\Program\ Files\\QEMU\\qemu-system-x86_64.exe [args]"

Example of a production QEMU command:

qemuArgs = "C:\\Program\ Files\\QEMU\\qemu-system-x86_64.exe -M q35,usb=on,acpi=on,hpet=off -cpu host -accel whpx -m 2G -smp cores=2 -device usb-tablet -nic none -hda C:\\collabvm\\images\\vm1.qcow2"

Running your VM

Now that everything is set up, you can bring your VM online. To run the server right from your terminal, run the following command:

yarn serve

Or alternatively, to run it directly:

node cvmts/dist/index.js

Running a local webapp

Before you put your VM on the UserVM roster, you'll probably want to test it out for yourself. For that, we'll throw up a test webapp. Start by cloning the source:

cd C:\collabvm
git clone https://github.com/computernewb/collab-vm-1.2-webapp.git --recursive
cd collab-vm-1.2-webapp

Then, copy config.example.json to config.json, and replace ServerAddresses with your server address:

    "ServerAddresses": [
        "ws://127.0.0.1:6004",
    ],

Now you can build the webapp, and serve it:

yarn
yarn build
yarn serve

This will run the webapp at 127.0.0.1:1234, which you can navigate to in your browser. If all went well, your VM should show up. If not, and you don't know why, join our discord and ask for help there!

Setting up a service

We will now set your VM up as a background service using the NSSM runner.

In admin CMD:

nssm install collabvm

This will open the NSSM setup GUI. Configure each page as follows

Application

Path: C:\Program Files\nodejs\node.exe

Startup directory: C:\collabvm\collabvm-1.2.ts

Arguments: C:\collabvm\collabvm-1.2.ts\cvmts\dist\index.js

Details

Startup type: Automatic if you want your VM to start with your computer, Manual if you want to start it manually

Log on

Log on as: Virtual Service Account (very important for security)

I/O

Output (stdout): C:\collabvm\out.log

Error (stderr): C:\collabvm\err.log


Permissions

Give the CollabVM Virtual Service User permissions to the C:\collabvm directory:

icacls C:\collabvm /grant "NT SERVICE\collabvm:F" /Q /C /T

NOTE: If you encounter permissions errors when running the CollabVM service after adding new VM images, run this command again.

Starting the service

You can now start your VM with:

net start collabvm

And stop it with:

net stop collabvm