UserVM Handbook: Difference between revisions

no edit summary
No edit summary
No edit summary
}}
=== Prepare the server ===
Now let's clone the source. ThisIt's isrecommended assumingthat you're indo yourthis somewhere like /srv/collabvm or /home/collabvm. directoryFor butthe youpurposes canof this guide we'll cloneuse itthe whereverformer.
{{code|
sudo mkdir -p /srv/collabvm
git clone https://github.com/computernewb/collabvm-1.2.ts.git
sudo chown -R $USER /srv/collabvm # Temporary, we'll change this to a dedicated CollabVM user later
cd collabvm-1.2.ts
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.
<tr><td>snapshots</td><td>Whether 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.</td></tr>
<tr><td>qmpSockDir</td><td>Directory for QEMU to put its QMP socket for internal use. This can stay default unless you have a special reason to change it</td></tr>
<tr><td>node</td><td>A unique ID for your VM. Your VM will be directly accessible at <code>https://computernewb.com/collab-vm/user-vm/#&gtlt;this id&gt;</code>. You should take care to name this something separate from any other VM on the UserVM roster, or your VM might be unaccessible</td></tr>
<tr><td>displayname</td><td>VM title that shows up in the list. Format with HTML</td></tr>
<tr><td>motd</td><td>Message of the day, displayed when someone joins your VM. Format with HTML</td></tr>
<tr><td>voteTime</td><td>How long a vote to reset lasts, before results are tallied</td></tr>
<tr><td>voteCooldown</td><td>How long before another reset vote can be started after one ends</td></tr>
<tr><td>adminpass</td><trtd>SHA256 hash of your admin password. Can be generated with the command <code>printf &quot;&lt;your admin password&quot;&gt; | sha256sum -</code>. Make sure this is something hard to guess as anyone with this password could execute arbitrary commands on your server.</td></tr>
<tr><td>modpass</td><td>SHA256 hash of your mod password. Generated same as admin. Does nothing if the moderator rank is not enabled.</td></tr>
<tr><td><b>moderatorPermissions</b></td><td>Controls the individual actions a moderator can do. Each one is described below. Does nothing if the moderator rank is not enabled.</td></tr>
<tr><td>xss</td><td>Send 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.</td></tr>
</table>
=== 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 <code>https://yoursite.xyz/collab-vm/</code> rather than <code>http://yoursite.xyz:6004</code>. 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 [https://computernewb.com/~elijah/wsproxy_params wsproxy_params] to your Nginx directory, which enables WebSocket proxying. Here's a one-liner to do that:
{{code|
sudo curl https://computernewb.com/~elijah/wsproxy_params -o /etc/nginx/wsproxy_params
}}
Next, you can add the following to your Nginx server block:
{{code|
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:
{{code|
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:
{{code|
npm run serve
}}
Or alternatively, to run it directly:
{{code|
node build/index.js
}}
=== Setting up a service ===
While it's useful and convenient to run your VM from the console while debugging, we <b>strongly</b> 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
{{code|
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 <code>/etc/systemd/system/collabvm.service</code> (Change the filename accordingly)
 
{{code|<nowiki>
[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
</nowiki>}}
 
Reload the daemon cache:
{{code|
sudo systemctl daemon-reload
}}
Then you can start your VM with:
{{code|
sudo systemctl start collabvm
}}
And make it automatically run on startup with:
{{code|
sudo systemctl enable collabvm
}}
 
==== OpenRC ====
Put the following into /etc/init.d/collabvm to make your VM an OpenRC service (change filename as appropriate):
{{code|<nowiki>
#!/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"
</nowiki>}}
Make it executable:
{{code|
sudo chmod +x /etc/init.d/collabvm
}}
Now you can start your VM with:
{{code|
sudo rc-service collabvm start
}}
And make it run on startup with:
{{code|
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:
{{code|
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:
{{code|
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:
{{code|
npm run build
npm run serve
}}
This will run the webapp at <code>127.0.0.1:3000</code>, 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 [https://discord.gg/a4kqb4mGyX Discord], and harass @Elijah.r#9517 in #support with the URL to your VM. It should be added in a timely manner.