Setting Up Mozilla Hubs Cloud for an Event—a How-To

Will this guide be of help to you?

Why should one set up their own instance of Mozilla Hubs on the Cloud? Why not just use the “basic” instance that they provide for free?

Pros of creating a Cloud instance:

Functionality: With a bespoke instance, a programmer can fork the Mozilla Hubs code from GitHub and use JavaScript to modify it to add new functionality.
Personalization: Can change branding, links (TOS, links to program or institution, etc), change the color scheme, etc.
Security: can introduce measures to prevent “Hubs bombing”.
Better performance: Can increase size of rooms past the default (25 people) and better guarantee that the rooms will still function appropriately.

Cons:

People-time / effort: Once used to it, upkeep is simple, but it can take some time to get used to, especially if one is not used to working in the hosting platform (AWS or DigitalOcean) used.
Money: Hosting the hubs instance will cost money, especially if being hosted at a high level for a long time. Fortunately, if being used for a single event, one can run Hubs on a cheaper level (using fewer resources) for setup and testing, and only upgrade the hosts during the event itself.

If this still seems like a good option for you, here’s a guide for setting up Mozilla Hubs in AWS (DigitalOcean, another platform to host on, is still in the alpha stage of development).

Setup (1-2 weeks before the event, at minimum)

Mozilla Hubs has good guides for starting out if you want to check those out. Instead of going over the same information here, I’ll talk about what choices, in my experience, lead to the best results for the least amount of time and energy.

Start with this quickstart guide. Make sure to do the prerequisites (“Before creating the Hubs Cloud Stack”) at the top of the page before continuing, as once you start setting up the stack you’ll have to restart if certain prerequisites aren’t already met. As some of the prerequisites are non-trivial, here’s some explanations, numbered corresponding to the numbers of the prerequisites in the quickstart guide.

More information on prerequisites

Create an account on AWS: if you’re working under a large organization, they may have to set this up for you, so I would recommend asking around to find out.
There are 3 “recipes” for domain setup. All of these “recipes” cost the same amount of money, but changing recipes after having already set up with one recipe may cost an extra $10-20, so try to pick out the best recipe for you to start with. Here’s some pros and cons for each recipe:

Recipe	Pros	Cons
Recipe 1	Easiest to prototype, easiest to turn off/on (to save costs in the long term)	Can only use domains that aren’t already in use (e.g. could not host on hubs.site.com if site.com is in use)
Recipe 2	Can use same domain for other sites (for eg if hubs is hosted on hubs.site.com, can use site.com or other.site.com for other sites)	Can only use domains that can be hosted on AWS’s Route 53 (for example, could not host on hubs.site.com if site.com isn’t on AWS
Recipe 3	Can use any domain not set up on Route 53	Every time the instance is power-cycled, someone with access to the domain will have to update the CNAME record on the main domain’s DNS servers

Feel free to check out the linked documentation on personal / enterprise, but in the end I would recommend using the Enterprise set-up, as it can be changed to be just like a Personal instance (by decreasing the number of servers), but Personal can’t be used as Enterprise.

Set up the stack

To start off development, you don’t need more than a single app server and a single streaming server, both set to the t4.micro instance. This allows you to keep costs down, and will work fine as long as too many people aren’t concurrently developing in Hubs. After the stack is set up, you can always go to CloudFormations, find the stack, and Update Stack to change this as well as other settings (see Performance for more).

What to do after initial setup

All administrator information and settings will be available at hubs.mysite.com/admin#.

One important thing that needs to be done before any additional accounts (apart from the administrator’s account) can be created is to get your AWS account’s Simple Email Service (SES) out of the sandbox. Follow the steps here for that.

After that, you also need to include at least one avatar and one scene for use. The Hubs instance itself will help you through this– there are a lot of free assets that are linked to from the “Import Content” tab on the left.

Paste URLs and .pack files (both of which can be found by clicking the “FIND AVATARS & SCENES” button on this page) into the text field and click the red button. Once the file(s) load, click on the checkboxes on the left to select/deselect content to import, click the checkboxes to the right of that to define “featured” assets (easiest to find when creating or entering a new room) and “default” assets. Go to the bottom of the page and hit the red “Import items” button.

And that’s it! People should now be able to create accounts and host rooms in Hubs. But there’s still a lot more than can be done. We’ll go over these, arranged in the same order as our “pros” above.

Functionality

One can fork the Github repository here and follow the steps here to get set up with your own version of the Mozilla Cloud code. However, we have not done this yet, and so don’t have any additional information or tips on it.

Security

There are a couple of things that I’d recommend doing as soon as possible after creating your Hubs instance:

Shut down creation of accounts by going to Setup->App Settings->Features-> Disable Account creation. Now only administrators will be able to create accounts.
Require an account to enter a room in your Hubs instance by going to Setup->App Settings->Rooms->Require Accounts for Room Access.

Now that administrators have the sole ability to create new accounts, they can do so in one of two ways, both through the admin console.

One by one: Go to the Accounts tab and enter emails and usernames near the top of the page.
In Batch: Once on the admin page, open the browser console (e.g. on Windows/Chrome, Ctrl+Shift+I) and enter the following commands (taken from the Mozilla Hubs discord):

To set up the list of emails (if the emails are in a spreadsheet or a text document, a simple script may be useful in generating this list of emails)

var mails =",:usr1,:usr2";

To actually create the accounts on the server

var m=mails.split(",").map(m=>{const e=m.trim().split(":");return {email:e[0],name:e[1]||e[0].split("@")[0]}});var xhr=new XMLHttpRequest();xhr.open("POST",window.location.origin+"/api/v1/accounts",true);xhr.setRequestHeader('Content-Type','application/json');xhr.setRequestHeader('authorization',`bearer ${APP.store.state.credentials.token}`);xhr.onload=function(){if(this.status===207){console.log("response:",this.status,"OK");for(const [i,v] of JSON.parse(this.responseText).entries()){if(v.status===200){console.log(v.body.data.login.email,"OK")}else{let s="";v.body.errors.forEach(e=>{s+=`${m[/\[(\d+)\]/.exec(e.source)[1]].email}\t${e.detail}\t`});console.log(s)}}}else console.log(this.status,this.statusText)};xhr.send(`{"data":${JSON.stringify(m)}}`);

Now, users will be able to log into premade accounts. Mozilla Hubs doesn’t use User IDs and passwords, it just uses emails and email verification. Because of this, once an account has been created, a user will have to go through the following steps before entering a room in your Hubs instance:

Go to hubs.yoursite.com
Click the “Sign In” button in the top right corner
Enter email address the account was created under and hit the green “next” button
Check their email for a link, typically from or (if using domain Recipe 3), making sure to check their spam/junk folders
Click on the link in the verification email

Now they should be able to enter rooms as long as they use the same computer and browser they used to sign in.

Performance

Improving performance is done by updating the stack. Updating the stack means making any major changes to the setup of the stack– changing domains, turning it off/on, up or downgrading the resources being used, etc.

To perform a stack update, go to AWS Console -> Cloud Formations, find the appropriate stack and click “Update Stack” near the top of the page. This will open up the same page you saw while creating the stack, and allow you to change some settings. Adding servers, as well as upgrading servers, will increase performance, but increase cost. Use the table here to see what settings would be good for your needs- https://hubs.mozilla.com/docs/hubs-cloud-aws-estimated-ccu-limits.html

We found the table to be quite confusing, though, so here’s what the different parts of it mean:

AWS instance type: this will be what you pick while updating the stack
vCPUs: if you’re just going to be hosting a “tall” event- one large room, you want around (number of people ^2) / 1000 vCPUs
CCUs (Concurrent users): how many people will be using the hubs instance, across the number of rooms listed (if not specified, across all rooms), at the same time.
Active/Inactive CCU: inactive users are those simply watching through the lobby, or not moving at all in the room. Active users are those in the room, moving around and interacting with objects or speaking.
If you’re going to have one room with speakers and everyone else in the lobby, use the 4th and 5th columns, depending on how many active users there will be, to see how many can be supported in the lobby.
If you’re planning to have a “wide” conference, with many rooms with fewer (around 25) people, use the last column to see how many such rooms would be supported.
Important thing to keep in mind—these numbers don’t translate with simple math. i.e. if an instance can support 2 rooms with 25 people, you can’t necessarily support 1 room with 50 people. It would support closer to 35ish people. If you want to set up a very specific set of rooms (like 2 rooms with 50 people and 2 with 30 people), I’d recommend making an educated guess and then testing that specifically on a variety of instances.

Personalization

Here is a guide to changing the aesthetics of your Hubs instance.You can also integrate other services by using the information here.

Right Before the Event

Updates to the stack should be made, just in case, at least a full hour before the event (even though it usually takes about 20 minutes for changes to propagate).

I’d also recommend having just one person start all the necessary rooms on one computer. These rooms can be accessed in a number of different ways:

When creating the rooms, click the option that will put these rooms on the homepage of your hubs instance. Now, attendees will only have to go to hubs.site.com to get links to all the listed rooms.
Create all the rooms and put all the links in an accessible location online.
Set up links between different rooms by copying a link to one room and pasting it into a different one.

When you try to create a new room with one already open, Hubs by default tries to close the first room. To prevent this when setting up multiple rooms, follow these steps after creating the first room:

Click on the hamburger menu in the top left corner
Click on Preferences
Go to the “Misc” tab
Press the check boxes next to both “Disable auto-exit when…” options

Right After the Event

Once the event is complete, it is recommended to shut down or downgrade the Hubs instance as soon as possible to reduce unnecessary costs. Go through step 1, as well as one of the steps from 2-4, depending on your future needs.

Close all rooms: For each room
1. Click on the hamburger menu in the top left corner
2. Click on “Close Room” and press the green button to confirm
If the instance will have more development soon, downgrade the instance by going through the steps to “Update Stack”, and decrease the number and size of servers. This has no irreversible effect on the instance and will keep the instance fully accessible. You’ll still be paying for the database storage being used, the Stack being used, and costs of the downgraded servers.
If the instance does not need to be accessible for a time, but enough development has been done or changes have been made that going through it all again would be too much, turn the stack offline by going through the steps to “Update Stack”, and change the setting for “Offline Mode->Stack Mode” to Offline. This has no irreversible effect on the instance, but will make the instance inaccessible until the stack is updated back to online (via the same setting in “Update Stack”). You’ll still be paying for the database storage being used (which will get cheaper if not accessed for a few days) and the Stack being used.
If the instance never needs to be used again, go to the same page where you’d usually click “Update Stack” and instead click on the “Delete Stack” button next to it, and follow the given instructions. This irreversibly deletes the hubs instance. You keep access to the domains, but all changes and information in the Hubs instance will be removed. You will no longer be paying for anything apart from possible recurring costs of the domains. You can return these domains wherever you bought them to stop this from happening.

Conclusion

Using Hubs for a conference can be aggravating at times, but can elevate an event. Being able to talk to and “see” others, with spatialized audio allowing for small group and 1-on-1 conversations, is a huge change from, say, Zoom, where aside from breakout rooms, one can only use voice to address everyone else on a call.

Setting up your own instance of Hubs Cloud allows for a large (theoretically, by forking the original GitHub repository, infinite) amount of specialization for your event. Adding in branding, security measures, and whatever additional functionality you need to make Hubs Cloud work for your specific needs can make a big difference in the success of events in this era of COVID-19.

Even after this time is over and we can attend in-person events again, virtual events, or at least events augmented by virtual components, will always have certain advantages that in-person events don’t. People are able to attend virtual events regardless of physical location or need for travel, allowing people from a greater range of socioeconomic backgrounds and mobility considerations to attend events that may be of interest to them. These events are also cheaper by far to organize compared to in-person events—the Hubs portion of our recent event of around 100 people cost less than $80, the majority of which was spent purchasing domains that we will now have for a year. As a result, getting experience, both personal and institutional, in setting up and hosting these events does not need to be, and in my opinion should not be, just a short term skill.

If you have any questions or suggestions for changes to this guide, feel free to contact me at .

I’m also very interested in the use of these newer technologies to attempt to address a variety of social ills, so please feel free to reach out if you have interesting research you came across or are doing, or just want to chat about a shared interest!