CollabVM Server 1.x/Server setup for beginners

This guide is intended to help get you setup with CollabVM 1.2.11 along with an NGINX server to handle your requests. You may host it publicly or run it privately. These instructions are tested only with Debian 11 and CollabVM 1.2.11. If you vary, you will have to substitute commands for your own. Basic Linux knowledge is strongly recommended.

Installation

Basic server requirements

• OS: Windows is not supported (but works). As said, these instructions are tested with Debian 11. Most Linux distributions will work, however.
• CPU: Preferably one which supports hardware virtualization. It is not required, but performance may suffer without it.
• RAM: You will need enough RAM to host your OS, CollabVM and the associated virtual machine. Have at least 2 GB of RAM free.
• Disk: Technically you need only about 50 megabytes of storage to run CollabVM, however you will need space for NGINX and your associated VM. Have atleast 4 GB of free storage, much more (>16GB) if you are hosting full Windows VMs.
• Permissions: You'll likely need root-level access to the server you're using in order to install packages for the system. However, collab-vm-server should NEVER be run as root! (or administrator privileges, when on Windows)

collab-vm-server setup

Do the following under a user with limited privileges (with the exception of sudo commands, if you wish):

1. You will need to grab the required libraries and some additional tools for collab-vm-server:
   • sudo apt install -y libboost-dev libboost-system-dev libcairo-dev libvncserver-dev libc-dev libturbojpeg-dev libsqlite3-dev make clang git
2. Next, you'll want to clone (download) the collab-vm-server repository: git clone https://github.com/computernewb/collab-vm-server-1.2.git -b release/1.2.11 --recurse-submodules
3. Now, change directory: cd collab-vm-server
4. Since we will run collab-vm-server under NGINX, we will need to modify two files:
   • Using the editor of your choice, edit the file src/websocketmm/websocket_user.cpp inside the CollabVM source code. Remove the double slashes in the line containing //#define WEBSOCKETMM_SUPPORT_PROXYING.
   • The next file to edit is src/CollabVM.cpp. Here, look for a line containing server_->start("0.0.0.0", port);. Change the 0.0.0.0 to 127.0.0.1
     • What we've done here is make it so CollabVM listens only on localhost. This way, malicious users cannot spoof their IP address by setting headers.
5. To compile collab-vm-server, execute this command: make -j$(nproc) JPEG=1
   • If you would not like JPEG support (not recommended!) you can leave out the JPEG=1 flag. Do not disable this unless you know what you are doing.
   • Note that this command will also use all of your cores, if you would like to utilize less cores, replace $(nproc) with the amount of cores you'd like to use

The collab-vm-binary is now compiled and ready to be used. It doesn't provide a proper HTTP server though, so it will not run

Webapp setup

Again, continue doing the following here under a user with limited privileges.

Main webapp

1. Go back 1 directory: cd ..
2. Install node.js:
   1. First, you need curl: sudo apt install -y curl
   2. Run this command: curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   3. Then install it: sudo apt install -y nodejs
3. Get the web app: git clone https://github.com/computernewb/collab-vm-web-app.git
4. Change directory into the webapp cd collab-vm-web-app/
5. Install the required packages: npm i
6. And install gulp globally: sudo npm i -g gulp
7. Time to edit another file:
   • Edit src/js/collab-vm/common.js, look for the line containing serverAddress: window.location.host,, change it to serverAddress: window.location.host + '/cvmws',
8. Now run gulp, let it build the web app.

Admin webapp

1. Go back 1 directory, once again: cd ..
2. Grab the admin webapp: git clone https://github.com/computernewb/collab-vm-admin-web-app.git
3. Now change directory into the admin webapp cd collab-vm-admin-web-app/
4. Then install the packages, once again: npm i
5. We need to modify the same file:
   • Edit src/collab-vm/common.js, this time replacing var serverAddress = window.location.host; with var serverAddress = window.location.host + '/cvmws';
6. Now run gulp once again: gulp

Constructing your HTTP directory

We will be creating the directory in /home/test/collab-vm-www, please substitute the commands as needed.

1. First we will create the directory: mkdir /home/test/collab-vm-www/
2. Now we will add a file inside:
   • Create the file index.html with the following content:

     <!DOCTYPE html>
     <html>
        <head>
           <title>...</title>
           <meta http-equiv="refresh" content="0; url=/collab-vm/" />
        </head>
        <body>
        </body>
     </html>
     

3. Next, copy the main webapp into your www directory: cp -r collab-vm-web-app/build /home/test/collab-vm-www/collab-vm (Don't forget the collab-vm/)
4. And the admin webapp: cp -r collab-vm-admin-web-app/build /home/test/collab-vm-www/admin

Now you have a working HTTP root for your Collab VM installation. We will be using NGINX in the next step in order to host this directory.

NGINX installation

We will be installing and configuring NGINX to host our webapp and proxy connections to the collab-vm-server instance. In this case, we are using port 6004, with collab-vm-server using port 6005 and our root directory being the same as previously (/home/test/collab-vm-www). We are also not accepting IPv6 connections, which may need some additional configuration.

1. First, install NGINX: sudo apt install nginx -y
2. Next, you will want to add an additional site configuration to NGINX.
   • Create the file /etc/nginx/sites-enabled/collab-vm, and insert the following contents inside. If needed, substitute the values as necessary. Root privileges might be required to edit this file.

     server {
       listen 6004; # Listen on port 6004
       access_log /var/log/nginx/cvm.log; # Log visitors to this file
       root /home/test/collab-vm-www/; # This will be your root www directory
       location /cvmws {
         proxy_pass http://127.0.0.1:6005; # This will be the port collab-vm-server will be listening on
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "Upgrade";
         proxy_set_header Host $host:$server_port;
         proxy_buffering off;
         proxy_redirect off;
         proxy_set_header Sec-WebSocket-Extensions  $http_sec_websocket_extensions;
         proxy_set_header Sec-WebSocket-Protocol  $http_sec_websocket_protocol;
         proxy_set_header Sec-WebSocket-Key $http_sec_websocket_key;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_connect_timeout 10s;
         proxy_read_timeout 36000s;
         proxy_temp_file_write_size 16k;
       }
       location / {
         try_files $uri $uri/ =404;
       }
     }
     

3. Now, enable and start NGINX using these commands:
   1. sudo systemctl enable nginx
   2. sudo systemctl start nginx

Now, visit your server's IP address on port 6004. If the IP address were 192.168.1.100, then visit http://192.168.1.100:6004/ in your browser. It should load the CollabVM interface with an endless loading spinner.