Introduction

This repo contains technical knowledge about mozilla hubs.

Let's help each other.

If you have advice or experience sharing about:

• Best practice
• Server hosting
• Server resource usages
• Tips

Please send me pull request or send me a message.

You can send me a message via discord

albirrkarim#8171

Give me a star on this repository or give a donation with this button below for supporting me to always update this.

Paypal

Installing Mozilla Hubs Locally

My journey installing Mozilla hubs, I'm new to a project like this. so I'm confused. After 4 days of figuring out how this program work finally I can run Mozilla hubs on my MacBook air m1. I want to share with you how to do it.

For make it clear i provide this tutorial in youtube video. give me like and subscribe to supporting me making the other video about this.

This is about running Mozilla hubs locally. this is a detailed version, step by step what I do.

Remember! if you got a problem with npm or dependency that you cant to solve for 1 hour. Just restart your PC. Trust me.

I have done Hosting Mozilla Hubs on VPS

Disclaimer - this tutorial maybe isn't a best practice

Requirement:

Hardware:

• at least 8GB of RAM
• recommended using fast CPU

Software

• Node js installed. when I install this hubs I use v16

Knowledge

I assume you already know, if no you must up-skill first

• Javascript
• React js
• Basic Webpack dev server
• Basic Elixir and phoenix
• Basic Web Socket

Overview

The image above made with figma you can read more description on documentation

I also try to make software overview, architecture, and tables on the database. you can see my figma project

Summary

Reticulum is the main host. it sync position, rotation, state of object. Comunicates with client browser through http request and websocket.

Dialog sync video and audio user. comunicates with clients browser through websocket.

Hubs, Spoke serve static assets then reticulum takes it and forward to client browser.

postREST is a server that help hubs Admin to doing basic task like CRUD (create read update delete)

Hubs Admin use websocket to comunicates with postgREST for authentication (login). for CRUD purpose hubs admin send http request (GET, POST, etc) to reticulum then reticulum doing proxy pass to postgREST.

Attention!

There is major step Cloning and Preparation -> Setting up HOST -> Setting up HTTPS (SSL) -> Running

1. Cloning and preparation

1.1 Reticulum

It's a backend server that uses elixir and phoenix.

1.1.1 Clone

git clone https://github.com/mozilla/reticulum.git
cd reticulum

1.1.2 Install requirement

Postgres Database

Install on linux ubuntu

Install on mac

With brew for installing CLI Postgres

brew install postgres

Then create user/change password

user: postgres

password : postgres

and alter it

ALTER USER postgres WITH SUPERUSER

Elixir and Erlang (Elixir 1.12 and erlang version 23)

You can install those with follow this tutorial

Be careful about the version of elixir and erlang.

1.1.3 run this command

1. mix deps.get
2. mix ecto.create
   • If step 2 fails, you may need to change the password for the postgres role to match the password configured dev.exs.
   • From within the psql shell, enter ALTER USER postgres WITH PASSWORD 'postgres';
   • If you receive an error that the ret_dev database does not exist, (using psql again) enter create database ret_dev;
3. From the project directory mkdir -p storage/dev

1.1.4 Run Reticulum against a local Dialog instance

1. Update the Janus host in dev.exs:

dev_janus_host = "localhost"

2. Update the Janus port in dev.exs:

config :ret, Ret.JanusLoadStatus, default_janus_host: dev_janus_host, janus_port: 4443

3. Add the Dialog meta endpoint to the CSP rules in add_csp.ex:

default_janus_csp_rule =
   if default_janus_host,
      do: "wss://#{default_janus_host}:#{janus_port} https://#{default_janus_host}:#{janus_port} https://#{default_janus_host}:#{janus_port}/meta",
      else: ""

4. Find on google how to install coturn, and manage it

install coturn on ubuntu

5. Edit the Dialog configuration file turnserver.conf and update the PostgreSQL database connection string to use the coturn schema from the Reticulum database:

psql-userdb="host=localhost dbname=ret_dev user=postgres password=postgres options='-c search_path=coturn' connect_timeout=30"

1.2 Dialog

Using mediasoup RTC will handle audio and video real-time communication. like camera stream, share screen.

1.2.1 Clone and get dependencies

git clone https://github.com/mozilla/dialog.git
cd dialog
npm install

1.2.2 Setting up secret key

thanks to this comment

Generate RSA (Public and Private key) with generator online

make empty file perms.pub.pem and fill it with RSA Public key

Goto reticulum directory on reticulum/config/dev.exs change PermsToken with the RSA private key that you generate before.

config :ret, Ret.PermsToken, perms_key: "-----BEGIN RSA PRIVATE KEY----- paste here copyed key but add every line \n before END RSA PRIVATE KEY-----"

1.3 Spoke

In here you can create/edit the scenes/buildings whatever you call it.

1.3.1 Clone

git clone https://github.com/mozilla/Spoke.git
cd Spoke
yarn install

1.3.2 Set the base routes

I hope you know the basic react-router-dom with the default URL in slash / on localhost:9090

But in the end, we will access the spoke on localhost:4000/spoke

So we must set the base URL to /spoke

Add the ROUTER_BASE_PATH=/spoke params to the start command on package.json

cross-env NODE_ENV=development ROUTER_BASE_PATH=/spoke BASE_ASSETS_PATH=https://localhost:9090/ webpack-dev-server --mode development --https --cert certs/cert.pem --key certs/key.pem

1.4 Hubs

In this repo contains the hubs client and hubs admin (hubs/admin)

Clone and install dependencies

git clone https://github.com/mozilla/hubs.git
cd hubs
npm ci

1.5 Hubs Admin

from the hubs repo you can move to hubs/admin then run

npm install

2. Setting up HOST

We are not using hubs.local domain. we use localhost

so change every host configuration on reticulum, dialog, hubs, hubs admin, spoke.

3. Setting up HTTPS (SSL)

All the servers must serve with HTTPS. you must generate a certificate and key file

3.1 Generating certificate and making it trust

Open terminal in reticulum directory

run command

mix phx.gen.cert

It will generate key selfsigned_key.pem and certificate selfsigned.pem in the priv/cert folder

Rename selfsigned_key.pem to key.pem

Rename selfsigned.pem to cert.pem

Now we have key.pem and cert.pem file

In Mac OS, I don't know in windows or Linux. please find it yourself

Open the cert.pem on the tab system find that certificate then clicks twice and change to always trust.

Select the cert.pem and key.pem and copy it. next step we will distribute those two files into hubs, hubs admin, spoke, dialog, and reticulum.

Oke first set up in the reticulum.

3.2 Setting https for reticulum

On the config/dev.exs We must be setting the path for the certificate and key file.

3.3 Setting HTTPS for hubs

Paste that file into hubs/certs

We run hubs with npm run local right? so add additional params on package.json

--https --cert certs/cert.pem --key certs/key.pem

Like this picture

3.4 Setting HTTPS for hubs admin

Paste that file into hubs/admin/certs

We run hubs with npm run local right? so add additional params on package.json

--https --cert certs/cert.pem --key certs/key.pem

Like this picture

3.5 Setting HTTPS for spoke

Paste that file into spoke/certs

We run spoke with yarn start right? So change the start command

With this

cross-env NODE_ENV=development ROUTER_BASE_PATH=/spoke BASE_ASSETS_PATH=https://localhost:9090/ webpack-dev-server --mode development --https --cert certs/cert.pem --key certs/key.pem

Short description:

BASE_ASSETS_PATH = basicaly we run the spoke on localhost:9090

3.6 Setting https for dialog

Paste that file into dialog/certs

rename cert.pem to fullchain.pem

rename key.pem to privkey.pem

4. Running

Open five terminals. for each reticulum, dialog, spoke, hubs, hubs admin.

4.1 Run reticulum

with command

iex -S mix phx.server

4.2 Run dialog

Edit the start command on the package.json with

MEDIASOUP_LISTEN_IP=127.0.0.1 MEDIASOUP_ANNOUNCED_IP=127.0.0.1 DEBUG=${DEBUG:='*mediasoup* *INFO* *WARN* *ERROR*'} INTERACTIVE=${INTERACTIVE:='true'} node index.js

For giving params MEDIASOUP_LISTEN_IP and MEDIASOUP_ANNOUNCED_IP

Start dialog server with command:

npm run start

127.0.0.1 is the default IP of localhost on Mac / Linux you can look at the IP with this command:

sudo nano /etc/hosts

4.3 Run spoke

with command

yarn start

4.4 Run hubs and hubs admin

Each with command

npm run local

4.5 Run postgREST server

More about this is in this

Download postREST

sudo apt install libpq-dev
wget https://github.com/PostgREST/postgrest/releases/download/v9.0.0/postgrest-v9.0.0-linux-static-x64.tar.xz
tar -xf postgrest-v9.0.0-linux-static-x64.tar.xz

On reticulum iex

paste this

jwk = Application.get_env(:ret, Ret.PermsToken)[:perms_key] |> JOSE.JWK.from_pem(); JOSE.JWK.to_file("reticulum-jwk.json", jwk)

then it will create reticulum-jwk.json in your reticulum directory

Make reticulum.conf file

nano reticulum.conf

and paste

# reticulum.conf
db-uri = "postgres://postgres:postgres@localhost:5432/ret_dev"
db-schema = "ret0_admin"
db-anon-role = "postgres_anonymous"
jwt-secret = "@/absolute_path_to_your_file/reticulum-jwk.json"
jwt-aud = "ret_perms"
role-claim-key = ".postgrest_role"

then the folder looks like this (contain two files)

/
   postgrest
   reticulum.conf

then run postREST with

postgrest reticulum.conf

Urraaaa, Now you can access

with lock symbol (SSL secure)

Hubs

https://localhost:4000

Hubs admin

https://localhost:4000/admin

Spoke

https://localhost:4000/spoke

Paypal

Also read:

Hosting Mozilla Hubs on VPS

The Problem I Still Faced

The Problem I Faced and I Already Solved

Tips for Modification

Overview System With Figma

Experience Sharing About Hosting on Other Server