UserVM Handbook

From Computernewb Wiki
Revision as of 19:04, 14 February 2023 by Elijah (talk | contribs)
Jump to navigation Jump to search

Welcome to the official guide on setting up a UserVM.

Prerequisites

You'll need:

  • A machine with decent specs (8GB of RAM and a modern CPU, probably)
  • A Linux distribution; You can pick any mainstream distro, for the purposes of this guide I recommend either Debian/Devuan or Arch/Artix. I recommend the OpenRC versions (Devuan/Artix) but that's just preference, pick what you're comfortable with. Yes, Ubuntu will work, it's terrible though
  • A decently fast network that allows you to forward a port. We will not accept UserVMs behind services like ngrok. 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 Linux 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 Git

First up make sure you have git installed: 

sudo pacman -S --needed git # Arch
sudo apt install git # Debian

Prepare the server

Now let's clone the source. It's recommended that you do this somewhere like /srv/collabvm or /home/collabvm. For the purposes of this guide we'll use the former. 

sudo mkdir -p /srv/collabvm
sudo chown -R $USER /srv/collabvm # Temporary, we'll change this to a dedicated CollabVM user later
git clone https://github.com/computernewb/collabvm-1.2.ts.git /srv/collabvm/collabvm-1.2.ts
cd /srv/collabvm/collabvm-1.2.ts

Next, we need to install Node.js, as well as the server dependencies. First, node: 

sudo apt install npm nodejs # Debian
sudo pacman --needed -S npm nodejs # Arch

Then install dependencies 

npm i

Finally, build the server 

npm run 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)

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.

Config valueExplanation
hostHost IP for the server to bind to. 99% of the time this will be 127.0.0.1 on proxied instances and 0.0.0.0 on non-proxied (see below)
portPort for your server to bind to. This must be different for each VM you host, and cannot be the same as any other server running on your system (see the output of ss -tuln to see what ports are used)
proxyingIf your server will be behind a reverse proxy, usually Nginx. This isn't a requirement, however, we recommend you do so for things like SSL support, and minimizing the number of ports open on your server. This requires additional configuration of your web server. If you edit this, make sure to go back and update host accordingly
proxyAllowedIpsIPs allowed to reverse proxy your server. Can be ignored if you're not using proxying mode. 99% of the time, this will just be 127.0.0.1
qemuArgsCommand line to launch QEMU with. You'll have this from setting up your VM earlier. If you're not sure, check out the QEMU guides linked above
vncPortPort to be used internally for VNC. Must be at least 5900. You don't need to pay too much attention to this unless you're running multiple VMs (In which case just increment the port by 1 for each VM)
snapshotsWhether or not your VM should have vote resets, and reset to its initial state on server restart. If you disable this on a public VM, prepare for it to get trashed quickly.
qmpSockDirDirectory for QEMU to put its QMP socket for internal use. This can stay default unless you have a special reason to change it
nodeA unique ID for your VM. Your VM will be directly accessible at https://computernewb.com/collab-vm/user-vm/#<this id>. You should take care to name this something separate from any other VM on the UserVM roster, or your VM might be unaccessible
displaynameVM title that shows up in the list. Format with HTML
motdMessage of the day, displayed when someone joins your VM. Format with HTML
bancmdCommand to be run when you click the ban button. By default this adds a non-persistent iptables rule, but we recommend you change this
moderatorEnabledWhether or not the moderator rank is enabled, in addition to Admin.
usernameblacklistArray of usernames the server should not allow
maxChatLengthMax amount of characters a user can send in a chat message. Further characters will be truncated.
automuteWhether or not the server should automatically mute users who spam messages. You can also specify how many messages within how many seconds should trigger the mute.
tempMuteTimeHow long a temporary mute lasts
turnTimeHow long a turn lasts
voteTimeHow long a vote to reset lasts, before results are tallied
voteCooldownHow long before another reset vote can be started after one ends
adminpassSHA256 hash of your admin password. Can be generated with the command printf "<your admin password"> | sha256sum -. Make sure this is something hard to guess as anyone with this password could execute arbitrary commands on your server.
modpassSHA256 hash of your mod password. Generated same as admin. Does nothing if the moderator rank is not enabled.
moderatorPermissionsControls the individual actions a moderator can do. Each one is described below. Does nothing if the moderator rank is not enabled.
restoreReset the VM back to it's initial state.
rebootReboot the VM
banBan a user from your VM
forcevoteForcibly pass or cancel a vote to reset
muteMute a user, preventing them from chatting or taking turns
kickKick a user from the VM
bypassturnJump to the front of the turn queue, as well as clear the turn queue and end individual turns
renameRename another user
grabipGet the IP address of another user
xssSend a raw (not HTML-sanitized) chat message, allowing the execution of arbitrary scripts on another user's browser. Admins will not be affected by XSS messages sent by mods.

Setting up reverse proxying (Optional)

We strongly recommend you proxy your UserVM behind Nginx, to provide additional security and allow things like SSL. It also makes your VM look a lot cleaner, allowing people to access it on your main HTTP(s) port and on a subdirectory, like https://yoursite.xyz/collab-vm/ rather than http://yoursite.xyz:6004. Here's a brief description of how to set that up on the Nginx side. This assumes you already have your site set up with Nginx, and if not there are numerous guides for that around the internet.

First, you'll want to save wsproxy_params to your Nginx directory, which enables WebSocket proxying. Here's a one-liner to do that: 

sudo curl https://computernewb.com/~elijah/wsproxy_params -o /etc/nginx/wsproxy_params

Next, you can add the following to your Nginx server block: 

location /collab-vm/ {
    include wsproxy_params;
    proxy_pass http://127.0.0.1:6004/; # Replace 6004 if you changed the HTTP port in the config file.
}

If you have multiple VMs running, you can have them all proxied like so: 

location /collab-vm/vm1 {
    include wsproxy_params;
    proxy_pass http://127.0.0.1:6004/; 
}
location /collab-vm/vm2 {
    include wsproxy_params;
    proxy_pass http://127.0.0.1:6005/; 
}
# ...etc

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: 

npm run serve

Or alternatively, to run it directly: 

node build/index.js

Setting up a service

While it's useful and convenient to run your VM from the console while debugging, we strongly recommend you set it up as a service once you're ready to leave it on for extended periods of time. This is done differently depending on what init system your distro uses (Probably systemd, if you're not sure)

First, we highly recommend you create a separate user for CollabVM, to maximize security 

sudo useradd -rM collabvm
sudo chown -R collabvm:collabvm /srv/collabvm/ # Set the collabvm user as the owner of the server files

Systemd

To make your VM a systemd service, you can put the following into /etc/systemd/system/collabvm.service (Change the filename accordingly) 

[Unit]
Description=CollabVM

[Service]
Restart=always
Type=simple
User=collabvm
Group=collabvm
# Make sure to change the following two lines according to where you put your server.
# If you have multiple VMs, you can change WorkingDirectory to a different directory for each VM and leave ExecStart the same,
# allowing you to use the same server for all your VMs.
WorkingDirectory=/srv/collabvm/collabvm-1.2.ts/
ExecStart=/bin/node /srv/collabvm/collabvm-1.2.ts/build/index.js

[Install]
WantedBy=multi-user.target

Reload the daemon cache: 

sudo systemctl daemon-reload

Then you can start your VM with: 

sudo systemctl start collabvm

And make it automatically run on startup with: 

sudo systemctl enable collabvm

OpenRC

Put the following into /etc/init.d/collabvm to make your VM an OpenRC service (change filename as appropriate): 

#!/sbin/openrc-run
supervisor="supervise-daemon"
name="collabvm"
command="/bin/node"
command_args="/srv/collabvm/collabvm-1.2.ts/build/index.js"
# If you have multiple VMs, you can change --chdir to a different directory on each VM, to use different config files on the same server
supervise_daemon_args="--user collabvm --group collabvm --chdir /srv/collabvm/collabvm-1.2.ts --stdout /srv/collabvm/out.log --stderr /srv/collabvm/error.log"

Make it executable: 

sudo chmod +x /etc/init.d/collabvm

Now you can start your VM with: 

sudo rc-service collabvm start

And make it run on startup with: 

sudo rc-update add collabvm

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: 

git clone https://github.com/computernewb/collab-vm-1.2-webapp.git
cd collab-vm-1.2-webapp

Then edit src/common.js, and replace serverAddresses with your server address: 

    serverAddresses: [
        "ws://127.0.0.1:6004", # If you're not using proxying
        "wss://yoursite.xyz/collab-vm/", # If you are using proxying. Remove one of these lines.
    ]

Now you can build the webapp, and serve it: 

npm run build
npm run serve

This will run the webapp at 127.0.0.1:3000, 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!

Logging in as an admin (or mod)

Logging in is very simple. Just join the VM, and double click your username. Enter your admin or mod password into the prompt, and you should be authenticated and able to use staff actions.

Getting your UserVM on the roster

Now you can have your UserVM put on the roster! Join our Discord, and harass @Elijah.r#9517 in #support with the URL to your VM. It should be added in a timely manner.

Retrieved from "https://computernewb.com/w/index.php?title=UserVM_Handbook&oldid=2450"