Docker

You can use Docker to build and run code in a clean environment, especially one with different packages. This is especially helpful if your system is not able to run our standard build environment.

Visual Studio Code has excellent integration for Docker. We recommend installing the Docker extension from Microsoft.

Installing Docker Engine

For Linux, we recommend Docker Engine over Docker Desktop:

For Windows, we strongly advise installing Docker Engine within Windows Subsystem for Linux, as the user experience is much smoother in our experience.

Note

Linux and WSL users should be sure to follow the guides for Manage Docker as a non-root user and Configure Docker to start on boot outlined on the Post-installation steps for Linux | Docker Documentation.

For macOS, you’ll need to install Docker Desktop instead:

Docker Registry Login

We host Docker images on our own private registry run by our GitLab instance.

This section describes how to set this up for Linux, specifically Ubuntu, although the instructions should be the same across most distros.

For Windows or macOS, or for more options and information in general, see docker login | Docker Documentation

Installing and Configuring Pass

First, install pass on your system. This should be available in your distribution’s package manager. On Debian-based systems, run:

sudo apt install pass

Download and install the latest version of docker-credential-pass. This is usually downloaded as a precompiled binary and installed in place. The latest version can be found on the docker-credential-helpers GitHub Releases page

The latest installation instructions (as of writing) for most 64-bit systems is as follows:

cd /tmp
wget https://github.com/docker/docker-credential-helpers/releases/download/v0.8.0/docker-credential-pass-v0.8.0.linux-amd64
mv docker-credential-pass-v0.8.0.linux-amd64 docker-credential-pass
chmod +x docker-credential-pass
sudo install docker-credential-pass /usr/local/bin

Test that this installed correctly by running the following:

gpg --list-keys

This will show all public keys known to your computer, including any belonging to other people that you have stored for verification purposes. Scroll through to find your name and email, and then grab your key. (It’s the long value towards the top with all the uppercase numbers and letters).

For example, here’s mine:

pub   rsa4096 2022-03-02 [SC]
    FF4678D9D3A42F78D2885F8EE038FEDD4C3CF53D
uid           [ultimate] Jason C. McDonald (MousePaw Media) <jcmcdonald@mousepawmedia.com>
uid           [ultimate] [jpeg image of size 3881]
sub   rsa4096 2022-03-02 [E]

So, FF4678D9D3A42F78D2885F8EE038FEDD4C3CF53D would be my public key. Note, I cannot actually sign anything with that key unless I also have the private key on my system! (Of course, I do.)

If this step worked, skip down to Initialzing Pass.

New GPG Key

If you don’t have a GPG key, you can generate a new one easily:

gpg --gen-key

Press Enter to select the default for the first three options, and then confirm your choices by pressing y and Enter. Now it will prompt you for your real name, email address, and an optional comment.

If you choose, you can also set a passphrase at this time, although it is not required. If you do set a passphrase, be careful not to lose it! There is no way to reset it or recover a password for a GPG key.

At this time, you may see that the computer is trying to “gain entropy”. Just switch to another window or terminal and do other things for a bit. As you use the computer, it’ll create that entropy it needs.

Once you’re done, you’ll see that your key was created. Grab the key from the Look for the line marked pub, and get the key from after the first forward-slash (/).

Initialzing Pass

Initialize pass with the following command, substituting your GPG key in place of MYGPGKEYHERE:

pass init MYGPGKEYHERE

If all goes well, then the following command should work:

docker-credential-pass list

If pass is not configured, you’ll receive a warning like “pass store is uninitialized.”.

You’ll first need to generate a Personal Access Token on your MousePaw Media GitLab account.

In a browser, log into the MousePaw Media GitLab. Click your profile picture at the top of the left pane and select Preferences. On the left, select Access Tokens. Click Add new token.

Give your token a name, and select the scopes read_registry and write_registry. Then click Create personal access token.

A green box will appear at the top of the page with the heading Your new personal access token. Click the clipboard icon to the left of the text field to copy the access token.

Once you’ve copied this personal access key, open your terminal. Enter the following:

docker login gitlab.mousepawmedia.com

At the prompts, enter your username and your personal access token. If login is successful, you will see “Login Succeeded”.

You can now work with MousePaw Media’s private Docker image registry.