Hosting on Internet¶

Warning

Until now, those communications are not encrypted but are planned to be in a mid-term future (status).

This tutorial aims to guide you toward hosting a collaborative multi-user session on the internet. Hosting a session can be achieved in several ways:

From blender: hosting a session directly from the blender add-on panel.
From the dedicated server: hosting a session directly from the command line interface on a computer without blender.
Cloud Hosting Walkthrough: hosting a session on a dedicated cloud server such as Google Cloud’s free tier.

From blender¶

By default your router doesn’t allow anyone to share you connection. In order grant the server access to people from internet you have two main option:

The Using a connection sharing solution: the easiest way.
The Using port-forwarding: this way is the most unsecure. If you have no networking knowledge, you should definitely follow Using a connection sharing solution.

Using port-forwarding¶

The port forwarding method consists of configuring your network router to deny most traffic with a firewall, but to then allow particular internet traffic (like a multiuser connection) through the firewall on specified ports.

In order to know which ports are used by the add-on, please check the Port setup section. To set up port forwarding for each port you can follow this guide for example.

Once you have set up the network you can follow the Quick Start guide to begin using the multi-user add-on !

From the dedicated server¶

Warning

The dedicated server is developed to run directly on an internet server (like a VPS (Virtual Private Server)). You can also run it at home on a LAN but for internet hosting you need to follow the Using port-forwarding setup first. Please see Cloud Hosting Walkthrough for a detailed walkthrough of cloud hosting using Google Cloud.

The dedicated server allows you to host a session with simplicity from any location. It was developed to improve internet hosting performance (for example poor latency).

The dedicated server can be run in two ways:

Using a regular command line
Using a pre-configured image on docker engine

Note

There are shell scripts to conveniently start a dedicated server via either of these approaches available in the gitlab repository. See section: Server startup scripts

Using a regular command line¶

You can run the dedicated server on any platform by following these steps:

Firstly, download and intall python 3 (3.6 or above).
Install the latest version of the replication library:
python -m pip install replication
Launch the server with:
replication.serve

Hint

You can also specify a custom port (-p), timeout (-t), admin password (-pwd), log level (ERROR, WARNING, INFO or DEBUG) (-l) and log file (-lf) with the following optional arguments

replication.serve -p 5555 -pwd admin -t 5000 -l INFO -lf server.log

Here, for example, a server is instantiated on port 5555, with password ‘admin’, a 5 second timeout, and logging enabled.

As soon as the dedicated server is running, you can connect to it from blender by following How to join a session.

Hint

Some server commands are available to enable administrators to manage a multi-user session. Check Dedicated server management to learn more.

Using a pre-configured image on docker engine¶

Launching the dedicated server from a docker server is simple as running:

docker run -d \
    -p 5555-5560:5555-5560 \
    -e port=5555 \
    -e log_level=DEBUG \
    -e password=admin \
    -e timeout=5000 \
    registry.gitlab.com/slumber/multi-user/multi-user-server:latest

Please use the :latest tag, or otherwise use the URL of the most recent container available in the multi-user container registry. As soon as the dedicated server is running, you can connect to it from blender by following How to join a session.

You can check that your container is running, and find its ID and name with:

docker ps

Viewing logs in a docker container¶

Logs for the server running in a docker container can be accessed by outputting the container logs to a log file. First, you’ll need to know your container ID, which you can find by running:

docker ps

Then, output the container logs to a file:

docker logs your-container-id >& dockerserver.log

Note

If using WSL2 on Windows 10 (Windows Subsystem for Linux), it is preferable to run a dedicated server via regular command line approach (or the associated startup script) from within Windows - docker desktop for windows 10 usually uses the WSL2 backend where it is available.

Downloading logs from a docker container on a cloud-hosted server¶

If you’d like to pull the log files from a cloud-hosted server to submit to a developer for review, a simple process using SSH and SCP is as follows:

First SSH into your instance. You can either open the VM Instances console and use the browser terminal provided by Google Cloud (I had the best luck using the Google Chrome browser)… or you can see here for how to set up your instance for SSH access from your local terminal.

If using SSH from your terminal, first generate SSH keys (setting their access permissions to e.g. chmod 400 level whereby only the user has permissions) and submit the public key to the cloud-hosted VM instance, storing the private key on your local machine. Then, SSH into your cloud server from your local terminal, with the following command:

ssh -i PATH_TO_PRIVATE_KEY USERNAME@EXTERNAL_IP_ADDRESS

Use the private key which corresponds to the public key you uploaded, and the username associated with that key (visible in the Google Cloud console for your VM Instance). Use the external IP address for the server, available from the VM Instances console e.g.

ssh -i ~/.ssh/id_rsa user@xxx.xxx.xxx.xxx

Once you’ve connected to the server’s secure shell, you can generate a log file from the docker container running the replication server. First, you’ll need to know your container ID, which you can find by running:

docker ps

If you’re cloud-hosting with e.g. Google Cloud, your container will be the one associated with the registry address where your Docker image was located. e.g. registry.gitlab.com/slumber/multi-user/multi-user-server:latest

To view the docker container logs, run:

docker logs your-container-name

OR

docker logs your-container-id

To save the output to a file, run:

docker logs your-container-id >& dockerserver.log

Now that the server logs are available in a file, we can disconnect from the secure shell (SSH), and then copy the file to the local machine using SCP. In your local terminal, execute the following:

scp -i PATH_TO_PRIVATE_KEY USERNAME@EXTERNAL_IP_ADDRESS:"dockerserver.log" LOCAL_PATH_TO_COPY_FILE_TO

e.g.

scp -i ~/.ssh/id_rsa user@xxx.xxx.xxx.xxx:"dockerserver.log" .

This copies the file dockerserver.log generated in the previous step to the current directory on the local machine. From there, you can send it to the multi-user maintainers for review.

Note

See these notes for how to check server logs on Google Cloud using other tools.

Server startup scripts¶

Convenient scripts are available in the Gitlab repository: https://gitlab.com/slumber/multi-user/scripts/startup_scripts/

Simply run the relevant script in a shell on the host machine to start a server with one line of code via replication directly or via a docker container. Choose between the two methods:

./start-server.sh

or

./run-dockerfile.sh

Hint

Once your server is up and running, some commands are available to manage the session Dedicated server management

Dedicated server management¶

Here is the list of available commands from the dedicated server:

help or ?: Show all commands. Or, use help <command> to learn about another command
exit or Ctrl+C : Stop the server.
kick username: kick the provided user.
users: list all online users.

Also, see How to manage a session for more details on managing a server.

Managing a docker server from the command line¶

If you want to be able to manage a server running within a docker container, open the terminal on the host machine (or SSH in, if you are using cloud hosting), and then run

docker ps

to find your container id, and then

docker attach your-container-id

to attach to the STDOUT from the container. There, you can issue the server management commands detailed in Dedicated server management. Type ? and hit return/enter to see the available commands. Also, see How to manage a session for more details on managing a server.

Port setup¶

The multi-user network architecture is based on a client-server model. The communication protocol uses four ports to communicate with clients:

Commands: command transmission (such as snapshots, change_rights, etc.) [user-nominated port]
Subscriber : pull data [Commands port + 1]
Publisher : push data [Commands port + 2]
TTL (time to leave) : used to ping each client [Commands port + 3]

To know which ports will be used, you just have to read the port in your preferences.

Port in host settings

In the picture below we have setup our port to 5555 so the four ports will be:

Commands: 5555 (5555)
Subscriber: 5556 (5555 +1)
Publisher: 5557 (5555 +2)
TTL: 5558 (5555 +3)

Those four ports need to be accessible from the client otherwise multi-user won’t work at all !

Cloud Hosting Walkthrough¶

The following is a walkthrough for how to set up a multi-user dedicated server instance on a cloud hosting provider - in this case, Google Cloud. Google Cloud is a powerful hosting service with a worldwide network of servers. It offers a free trial which provides free cloud hosting for 90 days, and then a free tier which runs indefinitely thereafter, so long as you stay within the usage limits. ^^Thanks to community member @NotFood for the tip!

Cloud hosting is a little more complicated to set up, but it can be valuable if you are trying to host a session with multiple friends scattered about planet earth. This can resolve issues with data replication or slowdowns due to poor latency of some users (high ping). This guide may seem technical, but if you follow the steps, you should be able to succeed in hosting an internet server to co-create with other multi-user creators around the world.

Setup Process¶

1. Sign Up for Google Cloud¶

Let’s start by activating an account with Google Cloud. Go to https://www.cloud.google.com and click ‘Get Started For Free’

Google will ask you to login/signup, and to set up a billing account (Don’t worry. It will not be charged unless you explicitly enable billing and then run over your free credit allowance). You will need to choose a billing country (relevant for tax purposes). You will choose your server location at a later step.

2. Enable Billing and Compute Engine API¶

From here on, we will mostly stick to the instructions provided here. Nevertheless, the instructions for multi-user specifically are as follows.

In order to set up a Virtual Machine (VM) to host your server, you will need to enable the billing account which was created during your signup process. From your console, click on ‘Go to Checklist’ and then ‘Create a Billing Account’, following the prompts to choose the billing account that was created for you upon signup.

Now hit ‘Set Account’, and go back to your console.

Now enable the Compute Engine API. Click here to enable.

3. Create a Linux Virtual Machine Instance¶

Continue following the instructions to create a VM instance. However, once you’ve finished step 2 of ‘Create a virtual machine instance’, use the settings and steps for multi-user as follows.

3.1 Choose a Server Location¶

The most important settings which you will need to choose for your specific case are the server Region and Zone. You must choose a location which will provide the best ping for all of your fellow creators.

All you need to know is that you’ll probably want to choose a location near to where most of your collaborators are located. If your friends are spread out, somewhere in the middle which distributes the ping evenly to all users is best.

You can use this map to make a rough guess of the best server location, if you know your friends’ locations.

A much better approach is to have your users run a ping test for Google Cloud’s servers at https://www.gcping.com/

Have your collaborators open this webpage from their fastest browser, and press the play button. The play button turns to a stop icon while the ping test is running. When it is complete, the play button returns. You may need to refresh your browser to get this to work. You can replay the test to add more server locations to the scan, and stop when you are satisfied that the results are consistent.

Now, gather your friends’ data, and work down each user’s list from the top, until you find the first location which gives roughly the same ping for all users.

In general, global (using load balancing) will provide the best results, but beyond that, the US Central servers e.g. IOWA generally turn out best for a globally distributed bunch of creators. When in doubt, choose between the servers offered under the free tier

Oregon: us-west1
Iowa: us-central1
South Carolina: us-east1

For the following example, the server which gave the most balanced, and lowest average ping between two friends based in Europe and Australia was in Iowa. Salt Lake City would also be an excellent choice.

Left - European User | Right - Australian User

Now, input this server location in the ‘Region’ field for your instance, and leave the default zone which is then populated.

Note

You can read here for a deeper understanding about how to choose a good server location.

3.2 Configure the VM¶

You can deploy the replication server to your VM in either of the ways mentioned at From the dedicated server. That is, you can set it up Using a regular command line or Using a pre-configured image on docker engine. We will go through both options in this walkthrough. See Should I deploy a Docker Container or launch a server from Linux VM command-line? for more details on how to choose. Deploying a container is the recommended approach.

Option 1 - Deploy a container¶

If you are familiar with Docker, you’ll appreciate that it makes life a little simpler for us. While configuring your instance, you can check Deploy a container to this VM instance and copy in the URL of the latest docker image available from the multi-user container registry to the Container image field, or use the tag :latest

Your configuration with Docker should look like this

Make sure to choose the amount of memory you’d like your server to be able to handle (how much memory does your blender scene require?). In this example, I’ve chosen 4GB of RAM.

Click on Advanced container options and turn on Allocate a buffer for STDIN and Allocate a pseudo-TTY just in case you want to run an interactive shell in your container.

Optional server parameters¶

The default Docker image essentially runs the equivalent of:

replication.server -pwd admin -p 5555 -t 5000 -l DEBUG -lf multiuser_server.log

This means the server will be launched with ‘admin’ as the administrator password, run on ports 5555:5558, use a timeout of 5 seconds, verbose ‘DEBUG’ log level, and with log files written to ‘multiuser_server.log’. See Using a regular command line for a description of optional parameters.

Note

If you’d like to configure different server options from the default docker configuration, you can insert your options here by expanding ‘Advanced container options’

For example, I would like to launch my server with a different administrator password than the default, my own log filename, and a shorter 3-second (3000ms) timeout. I’ll click Add argument under Command arguments and paste the following command with options into the “command arguments” field:

replication.serve -pwd supersecretpassword -p 5555 -t 3000 -l DEBUG -lf logname.log

Now, my configuration should look like this:

The rest of the settings are now complete. Hit Create and your instance will go live. If you’ve taken this approach, you’re already almost there! Skip to 4. Setting up Firewall and opening Ports.

Hint

You can find further information on configuration options here. Also, see these notes for other options when deploying your server inside a container, including how to access the server’s logs.

Option 2 - Over SSH¶

Otherwise, we can run the dedicated server ourselves from the command-line over SSH.

While creating your instance, keep the default settings mentioned in the guide, however at step 4, choose Debian version 10. Also, there is no need to enable HTTP so skip step 6.

Your configuration should look like this

Make sure to choose the amount of memory you’d like your server to be able to handle (how much memory does your blender scene require?). In this example, I’ve chosen 4GB of RAM.

Now, finally, click ‘Create’ to generate your Virtual Machine Instance.

4. Setting up Firewall and opening Ports¶

Now that your VM is instanced, you’ll need to set up firewall rules, and open the ports required by multi-user. The documentation for VM firewalls on google cloud is here.

First, go to the dashboard showing your VM instances and note the ‘External IP’ address for later. This is the address of your server. Then, click ‘Set up Firewall Rules’.

Note down your External IP

Now you will need to create two rules. One to enable communication inbound to your server (ingress), and another to enable outbound communication from your server (egress). Click ‘Create Firewall’

Now create a rule exactly as in the image below for the outbound communication (egress).

Egress

Note

If you set a different port number in Optional server parameters, then use the ports indicated in Port setup

And another rule exactly as in the image below for the inbound communication (ingress).

Ingress

Finally, your firewall configuration should look like this.

Final Firewall Configuration

5. Install Replication Server into Virtual Machine¶

Note

Skip to 7. Initialise your Server in Blender if you’ve opted to launch the server by deploying a container. Your server is already live!

Now that we have set up our Virtual Machine instance, we can SSH into it, and install the Replication Server. Open the VM Instances console once more, and SSH into your instance. It’s easiest to use the browser terminal provided by Google Cloud (I had the best luck using the Google Chrome browser), but you can also see here for how to set up your instance for SSH access from your terminal.

Now, a terminal window should pop up in a new browser window looking something like this:

Remember, you had set up the VM with Debian 10. This comes with Python 3.7.3 already installed. The only dependency missing is to set up pip3. So, run:

sudo apt install python3-pip

And now lets install the latest version of replication:

sudo pip3 install replication==0.1.13

6. Launch Replication Server on VM Instance¶

We’re finally ready to launch the server. Simply run:

replication.serve -p 5555 -pwd admin -t 5000 -l INFO -lf server.log

See Using a regular command line for a description of optional parameters

And your replication server is live! It should stay running in the terminal window until you close it. Copy the external IP that you noted down earlier, available here and now you can open Blender and connect to your server!

7. Initialise your Server in Blender¶

Once in Blender, make sure your multi-user addon is updated to the latest version. update-version. Then, follow the instructions from How to join a session and connect as an admin user, using the password you launched the server with and the IP adress of the server. Then, click connect.

Now as the admin user, you can click on init and choose whether to initialise the server with a preloaded scene, or an empty scene.

Now your session is live!

If you made it this far, congratulations! You can now go ahead and share the external IP address with your friends and co-creators and have fun with real-time collaboration in Blender!

Hopefully, your cloud server setup has improved your group’s overall ping readings, and you’re in for a smooth and trouble-free co-creation session.

Note

If you should so desire, pay attention to your credit and follow the steps here to close your instance at your discretion.

Should I deploy a Docker Container or launch a server from Linux VM command-line?¶

Directly from Linux VM - This approach gives you control over your session more easily. However, your server may time out once your SSH link to the server is interrupted (for example, if the admin’s computer goes to sleep).
Deploy a Docker Container - This is the recommended approach. This approach is better for leaving a session running without supervision. It can however be more complicated to manage. Use this approach if you’d like a consistent experience with others in the multi-user community, pulling from the most up-to-date docker image maintained by @swann in the multi-user container registry.

Hosting on Internet¶

From blender¶

Using a connection sharing solution¶

1. Installation¶

2. Network creation¶

3. Network authorization¶

4. Network connection¶

Using port-forwarding¶

From the dedicated server¶

Using a regular command line¶

Using a pre-configured image on docker engine¶

Viewing logs in a docker container¶

Downloading logs from a docker container on a cloud-hosted server¶

Server startup scripts¶

Dedicated server management¶

Managing a docker server from the command line¶

Port setup¶

Cloud Hosting Walkthrough¶

Setup Process¶

1. Sign Up for Google Cloud¶

2. Enable Billing and Compute Engine API¶

3. Create a Linux Virtual Machine Instance¶

3.1 Choose a Server Location¶

3.2 Configure the VM¶

Option 1 - Deploy a container¶

Optional server parameters¶

Option 2 - Over SSH¶

4. Setting up Firewall and opening Ports¶

5. Install Replication Server into Virtual Machine¶

6. Launch Replication Server on VM Instance¶

7. Initialise your Server in Blender¶

Should I deploy a Docker Container or launch a server from Linux VM command-line?¶