Using dev containers in Apple macOS

Table of contents

• Using dev containers in Apple macOS
  • Local Installation on a computer running macOS
    • Install and configure Docker Desktop
    • Install VS Code for macOS
    • Install VS Code extensions
    • Install homebrew if you do not have it already
    • Install git using homebrew
    • Do global git configuration
    • Set up the git credential manager for use with Github authentication
      • Detailed G-Cubed repository cloning instructions using VS Code
  • Running Dev containers on macOS

Local Installation on a computer running macOS

To run dev containers locally (on your own computer running macOS), you need to install and configure:

• Docker Desktop;
• VS Code; and
• a number of VS Code extensions.

Install and configure Docker Desktop

Once you have installed Docker Desktop, start the application and ensure that it is running. You can check that it is running by looking for the Docker Desktop icon in the macOS Launchpad. You should not need to create a Docker account to use the application but it must be running to use dev containers. It can be configured to start on boot if you wish. When running, a Docker icon displays at the top of your screen. Make sure in the Docker settings that it is set to start Docker Desktop when you signn into your computer.

Click on the docker icon to see the list of dev containers on your computer. You should see a list of dev containers that you have previously run. If you have not run any dev containers, this list will be empty. The dev containers indicate whether they are running or not.

In Docker Desktop, go to Settings (the cog wheel in top right corner) / General and ensure that Scout (SBOM) indexing and enable background SBOM indexing are both turned OFF. You may need to scroll down to find those settings. Also, ensure that under Settings / Features in Development or Beta Features all Beta and Experimental features are turned OFF. These settings can otherwise adversely impact performance on computers with constrained capacity.

Install VS Code for macOS

Once VS Code for macOS is installed, try starting VS Code.

code .

Install VS Code extensions

The capabilities of VS Code can be augmented using VS Code extensions. If VS Code is running successfully then you need to install the VS Code Dev Containers extension, which lets you run Visual Studio Code inside a Docker container. Install it by clicking here and then clicking the Install the Dev Containers extension button. Once complete, review the instructions here to test the installation.

If this is successful then congratulations! Your installation has been successful. You are now ready to run our dev containers on your macOS computer.

Install homebrew if you do not have it already

Homebrew is used to install an up-to-date version of git.

• Installation instructions

Ensure you follow all of these instructions to make Homebrew available in the terminal. Importantly finish up by running the following terminal commands and then restarting the terminal.

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Install git using homebrew

• Instructions. Be sure to follow the Homebrew instructions rather than the XCode instructions.

The key instruction is to restart the terminal and run:

brew install git

Make sure that the homebrew version of git is the default one used in your terminal by running:

which git

The result should be:

/opt/homebrew/bin/git

or on Intel devices:

/usr/local/bin/git

If it is /usr/bin/git then you are still defaulting to the XCode version of git. That can be fixed by running:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Check that git is installed with:

git --version

Do global git configuration

git config --global user.name "Your name"
git config --global user.email "your email address that you use with Github"

Check these settings with:

git config -l global

Set up the git credential manager for use with Github authentication

brew install --cask git-credential-manager
git-credential-manager configure

Log into the Github website in your browser.

Clone a McKibbin Software Group repository to set up the credentials that will then be reused.

git clone https://github.com/OWNER/REPO.git

Detailed G-Cubed repository cloning instructions using VS Code

1. Change to or create the parent directory for your G-Cubed repository (eg ‘mkdir gcubed’, ‘cd gcubed’).

2. Start VS Code by typing code . (this is just shorthand for ‘open VS Code in the current directory’).

3. Type the key combination CMD + SHIFT + P to call up the search bar in VS Code.

4. Type git clone and select that option from the search bar in VS Code.

5. Enter the repository’s HTTPS cloning URL (you can copy this from the Github homepage for the repository).

All going well, VS Code will either clone the repo or prompt you for credentials and then clone the repo (though you will have to select the directory that you created above first). VS Code will use your credentials to authenticate with Github when accessing the remote repository to clone it.

Running Dev containers on macOS

1. Open a Terminal in macOS
2. Clone a dev container repository to your local drive. For instance:

git clone https://github.com/McKibbin-Software-Group/gcubed.com-model-2R.git

1. Change to the repository folder

cd gcubed.com-model-2R

1. Start VS Code

code .

[!NOTE] Requires the ‘dot’ / ‘full stop’ after code - this instructs VS Code to open the current folder.

All going well, VS Code should open and display all the files & directories in that folder.

[!NOTE] The dev container has not started yet. You can just edit the files in that clone of the repo, but none of the development environment is running and you can’t access the G-Cubed tools. VS Code may at this point offer to reopen as a dev container (select that) or you may need to manually open the container.

You can manually start the dev container by pressing COMMAND+SHIFT+P and typing reopen. You should see a search window open and the option Dev Containers: Reopen in Container should appear at or near the top of the list. Select that option.

[!TIP] You can open macOS Explorer in this location by typing open . - note the dot again here

You can finish the session and shut down the container by simply closing the VS Code window. You can restart your session by re-opening a Terminal, changing to the repository folder, and starting VS Code code .

You may also need to reopen the dev container from within VS Code.

[!TIP] By default VS Code remembers where you left off and will restart in the same location. Simply starting VS Code from within macOS should automatically restart the dev container and open the previous editor windows.