Skip to content

Commit

Permalink
Merge pull request #41 from zfox23/readme20230717
Browse files Browse the repository at this point in the history
Updates to hubs-compose/README.md, mainly for Windows folks
  • Loading branch information
bryanenders authored Jul 17, 2023
2 parents 3f9b332 + ce68331 commit 3a2152d
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 3 deletions.
38 changes: 35 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,34 @@ services used by Mozilla Hubs for local development.[^1]
security or scalability. Additionally the permissions files were generated for
development purposes only.

## Windows Prerequisites
### Summary
- (Optional) [Install WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)
- 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](https://learn.microsoft.com/en-us/windows/wsl/install)

#### ⚠️ 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](https://docs.docker.com/desktop/wsl/#turn-on-docker-desktop-wsl-2).

You can [read more about Docker Desktop + WSL2 on Docker's website.](https://docs.docker.com/desktop/wsl/#turn-on-docker-desktop-wsl-2)

### 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
Expand All @@ -15,17 +43,21 @@ certificates, you can visit https://hubs.local:4000 from your browser.
### Initial Setup

1. [Install Docker Compose](https://docs.docker.com/compose/install)
2. [Install Mutagen Compose](https://github.com/mutagen-io/mutagen-compose#system-requirements)
3. Add these entries to your hosts file:
2. [Install Mutagen](https://mutagen.io/documentation/introduction/installation)
3. [Install Mutagen Compose](https://github.com/mutagen-io/mutagen-compose#system-requirements)
- 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".)
4. Add these entries to your hosts file:

127.0.0.1 hubs.local
127.0.0.1 hubs-proxy.local

4. Initialize the services with `bin/init`
- On Windows, your plain-text `hosts` file is probably located at `C:\Windows\System32\drivers\etc\hosts`.
5. 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 with `mutagen daemon stop`.
* Stop containers `bin/down`
* Observe running containers with `bin/observe`[^2]
* Restore all services to a fresh state with `bin/reset`
Expand Down
8 changes: 8 additions & 0 deletions bin/up
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
#!/bin/bash
basedir=$(dirname "$0")/..

prefix='\n\033[1;37m'
suffix='\033[0m\n'
echo -e ${prefix}Starting mutagen daemon...$suffix
mutagen daemon start
echo -e ${prefix}The mutagen daemon will stay running until you stop it manually with \`mutagen daemon stop\`.$suffix

echo -e ${prefix}Running mutagen-compose...$suffix
mutagen-compose -f "$basedir"/docker-compose.yml up --build --detach

0 comments on commit 3a2152d

Please sign in to comment.