Custom Clients (Pro Plan)
This guide walks you through the steps of setting up and removing a custom client on your Hub for Professional plan subscribers.
Table of Contents
Introduction
Prerequisites
Part A: Set Up the Hubs Client
Part B: Prepare Your Custom Client Tarball
Part C: Locate Your turkeyauthtoken
Part D: Deploy Your Custom Client
Removing Your Custom Client
Introduction
Deploying a custom client to your Hub allows you to fully control the appearance and functionality of the Hubs 3D engine and frontend code. This feature is intended for subscribers with at least a beginner level of javascript development experience. Please be advised that deploying a custom client disables the automatic updates that the Hubs Team regularly deploys to subscription instances. You can follow our regular updates here.
If you need more assistance, we recommend following along with our Custom Client Tutorial Video.
Prerequisites
You must have a Custom Domain deployed on your Hub before you can upload a custom client.
Make sure you have docker installed on your device. Testing for this feature utilized docker version
20.10.21
.
Part A: Set Up the Hubs Client
Clone the Hubs github repository onto your device. Users deploying custom clients to subscriptions should use the
master
branch of the repository.Install the project's node dependencies by running
npm ci
. Make sure you are using node version16.16
. This process may take up to 30 minutes.Change directory into the folder of your project and run
npm run dev
to start a development server. Once the code has compiled, you will be able to access this development server atlocalhost:8080
on your web browser.Add your customizations to the Hubs code. See the For Developers section of these docs for information about how to get started with your customizations.
Troubleshooting
- The backend dev server is configured with CORS to only accept connections from "hubs.local:8080", so you will need to access it from that host. To do this, you likely want to add "hubs.local" and "hubs-proxy.local" to the local "hosts" file on your computer:
127.0.0.1 hubs.local
127.0.0.1 hubs-proxy.local
Part B: Prepare Your Custom Client Tarball
Change directory to the main folder of your project, make sure you have docker opened, and run
bash retpack.sh
The code may take up to an hour to complete depending on the size of your customizations and processing power of your computer. Once complete, it will return the following message and your tarball will be located at
./.retpack/retpack.tar.gz
.
### done ###
-rw-r--r--@ 1 mozilla staff {timestamp} ./.retpack/retpack.tar.gz
Troubleshooting
- If
npm ci
fails during the build process, there are a couple of options to fix this. First, verify that you are using node version16.16.0
. Second, if you are using a Mac computer with M1 silicon, runexport DOCKER_DEFAULT_PLATFORM=linux/amd64
before runningbash retpack.sh
.
turkeyauthtoken
Part C: Locate Your Open the developer tools in the subscription dashboard and navigate to the “Console” tab.
Run the following code in the console to get your token:
console.log(RegExp("_turkeyauthtoken"+"=[^;]+").exec(document.cookie)[0].slice(17))
Copy the long string of characters to be used in Part D. Please note that turkeyauthtokens are only valid for 12 hours.
Part D: Deploy Your Custom Client
Deploying a custom client will disable the automatic updates that the Hubs Team regularly deploys to subscription instances. If you choose to use a custom client, you are responsible for keeping up with these regular updates to ensure your code is functional.
Open your terminal, and run the following command with the 3 parameters surrounded by
< >
populated with your specific information from previous steps:
curl -X POST -F file='@<path-to-client-tarball-on-your-device>' -H "turkeyauthtoken:<token-value-from-part-c>" 'https://<native-hub-domain>/api/ita/deploy?app=hubs'
The terminal command may take several minutes to complete depending on the quantity and nature of your customization. Do not exit the terminal until the upload process has completed. Once successfully complete, it will return
done, reqId: <unique-ID-string>
. After a few minutes, you should see your customization on your Hub.After deploying, try to create a room to verify your customizations have taken place. If you are unable to see your customizations, email hubs-feedback@mozilla.com with the subject line
Hubs Custom Client Deployment Troubleshooting
and a description of your problem.
Removing Your Custom Client
Removing a custom client will re-enable the automatic updates that the Hubs Team regularly deploys to subscription instances.
Open your terminal, and run the following command with the 2 parameters surrounded by
< >
populated with your specific information from previous steps:
curl -X PATCH -H "turkeyauthtoken:<token-value-from-part-c>" 'https://<native-hub-domain>/api/ita/undeploy?app=hubs'
The terminal command should execute quickly and return the value
done
. After a few minutes, you should be able to access your Hub and should no longer see your customizations.