Hubs Compose
Hubs Compose is a Docker Compose setup than can be used to orchestrate all the services used by Mozilla Hubs for local development.1
Windows Prerequisites
Summary
- (Optional) Install WSL2
- Ensure Git checks out Unix line endings
- Use Git Bash to run scripts
(Optional) Install WSL2
Docker Desktop runs more quickly when it can use its WSL2-based engine. Docker Desktop can only use its WSL2 engine if WSL2 is installed.
There are also other benefits to installing WSL2, including being able to run scripts and programs that your Unix developer friends share with you.
To install WSL2, follow Microsoft's documentation here: Install Linux on Windows with WSL
⚠️ Potential Conflict
If you plan to run Docker Desktop on Windows, and you want to take advantage of Docker Desktop's faster WSL2 engine, and you already have WSL2 installed, you need to first uninstall any previous versions of Docker Engine and CLI installed directly through WSL2.
You can read more about Docker Desktop + WSL2 on Docker's website.
Use Unix Line Endings
Some scripts used to run hubs-compose
rely on those scripts containing Unix line endings. If you're running hubs-compose
on Windows, you may need to change your Git line endings setting to ensure your local files include Unix-style line endings.
To change this setting, open a Git Bash shell, then run git config --global core.autocrlf false
to ensure that the intended Unix-style line endings are preserved upon Git checkout.
If you've already cloned this hubs-compose
repository locally, you may have to delete your local copy of the repository and re-clone it after changing your line endings setting.
Use Git Bash
Some scripts used to run hubs-compose
are meant to run in a Unix-like bash
shell. The "Git Bash" shell included with Git - also known as MINGW64 - will work to run these scripts; the Windows Terminal will not work to run these scripts.
Usage
Once the containers are up and running and you have accepted the self-signed certificates, you can visit https://hubs.local:4000 from your browser.
Initial Setup
- Ensure that the version of Mutagen Compose you're installing matches the version of Mutagen that you installed. (If you install the latest versions at the same time, they will "match".)
-
Add these entries to your hosts file:
127.0.0.1 hubs.local 127.0.0.1 hubs-proxy.local
- On Windows, your plain-text
hosts
file is probably located atC:\Windows\System32\drivers\etc\hosts
.
- Initialize the services with
bin/init
Orchestration
- Start containers with
bin/up
bin/up
starts the Mutagen daemon automatically. The Mutagen daemon will stay running until you stop it manually withmutagen daemon stop
.
- Stop containers
bin/down
- Observe running containers with
bin/observe
2 - Restore all services to a fresh state with
bin/reset
- Update all service source code with
bin/services-update
- Update service dependencies with
bin/init
Self-Signed Certificates
Service communication is encrypted with self-signed Transport Layer Security
(TLS) certificates. You will need to accept the proxy certificate and the
certificate at each of the Hubs ports mapped in
docker-compose.yml
. At the time of this writing, that
means visiting these links in your web browser and following the prompts:
Admin panel access
To connect to the admin panel you will need to manually promote an account to admin.
Command Execution
Common commands can be easily executed inside a running container from your
shell using the scripts inside the given service’s bin/
directory. For
example, calling bin/mix deps.get
from ./services/reticulum/
will download
the dependencies for Reticulum.
Development
Architectural Decision Records
Records of architectural decisions
are stored in the decisions/
directory. If you make a decision that affects
“the structure, non-functional characteristics, dependencies, interfaces, or
construction techniques” of the project, please document it. If you
install ADR Tools, adr new
will generate the template for you.