Now that you have a working Hubs Cloud instance, you can create and deploy custom versions of the Hubs Client yourself! By forking the hubs repository, making code changes, then deploying it to your live instance.
Your custom client code will be based off of the
hubs-cloud branch which hosts Hubs client changes compatible with Hubs Cloud servers. Changes due to upgrades will be visible in merged PRs on the branch.
Setup your Custom Client with your fork and upstream
Setup your fork of the hubs repo
Your fork is a copy of the hubs repository on your github account.
- Create a github account
- Go to https://github.com/mozilla/hubs
- Click the "Fork" button in the upper right hand corner
- You'll be redirected to github.com/mozilla/hubs/fork
- Make sure to UNCHECK the 'Copy the master branch only' option so that you have access to all the branches
- Go to your newly forked repo (upper left should say "
/ hubs" NOT "mozilla/hubs")
- Click green "Code button" to open the clone options for your repo
- Copy the url, you'll need this copied url for the next steps (everyone new to git use HTTPS)
Next, you will be cloning this repo onto your local machine.
You'll need: git installed for this step.
Run the following commands. To setup your forked repo on your machine.
# Clone your forked hubs repository locally git clone <The url copied in Step 6> cd hubs git checkout hubs-cloud # to move to the hubs-cloud branch
The "hubs-cloud" branch should function as the "master" branch. Since Hubs Cloud clients are compatible with the hubs-cloud branch. For code changes, branch off this branch.
Setup upstream remotes
Upstream remote repository points to the original hubs repo, so when the hubs repo get updated, your fork can pull in those changes and stay up to date.
Next, setup the original hubs repo as a remote upstream repository to keep your branches up to date.
# Connect to the mozilla managed hubs repository git remote -v # should only print out "origin" your forked hubs repository url git remote add upstream https://github.com/mozilla/hubs.git git remote -v # now should see both origin + upstreams
You should see this printed:
origin <The url copied in Step 6> origin <The url copied in Step 6> upstream https://github.com/mozilla/hubs.git (fetch) upstream https://github.com/mozilla/hubs.git (push)
Success! You've set up your fork and upstream repositories on your machine.
Run your custom client
Now that you have the Hubs repository forked and cloned on your machine, you'll need to install some dependencies. You'll need Node JS installed first. Then you'll install the hubs dependencies. We recommend using
npm ci instead of
npm install so that you always use the versions of modules in the
To run the client against your Hubs Cloud stack and deploy code to it, you'll need to be authenticated. Run
npm run login and follow the instructions to authenticate (Warning: NOT
npm run login
Once you are logged in you can start up the local development server with
After you've made changes to your client's code you can deploy the changes to your Hubs Cloud stack with the
npm run deploy command. Once that has finished you should see the changes live on your site! Please expect the
npm run deploy command to take a while.
npm run deploy
Note: When running a deploy, ensure webpack-dev-server (
npm start) is not running. This may cause conflicts in the build process.
npm run deploy hangs on "Building Admin Console" for more than 20 minutes:
- Stop then restart
npm run deploy(sometimes it takes 2 tries to deploy)
- If it still hangs on "Building Admin Console" you may have a problem building the Admin Console
To test that your admin panel build is working, in your hubs repo root, try:
cd admin- be in the admin/ directory
npm run build
- If these commands succeed, try the
npm run deploycommand again.
- If these commands fail, try
npm ciand the
buildcommands one more time, then fix the error in your code, then try these commands again.
If at any point you want to revert your Hubs client back to using the Mozilla upstream version of the client, run
npm run undeploy.
npm run undeploy
Update your Custom Client to the latest
You need to pull in the latest changes to the hubs-cloud branch into your fork + code.
Hubs Cloud is updated every month, to ensure your Hubs Cloud custom client is up to date, you should do this regularly in case of changes. See Hubs Cloud Changelog for details.
Check your remotes for the upstream mozilla hubs repository. If not, follow "Setup remotes" steps above.
git remote -v # should see origin AND upstream fetch/push .git urls
Fetch and merge the upstream Mozilla hubs-cloud branch into your branch. Especially important after a Hubs Cloud update.
git fetch upstream # Gets all updates for your mozilla/hubs repo git checkout <your current hubs-cloud branch> git merge upstream/hubs-cloud # Merges updates from the hubs-cloud branch into your current branch
Resolve conflicts. Then, deploy the updates.
npm run deploy
Congrats! Your client is now updated to the latest and live!