Skip to content

Latest commit

 

History

History
149 lines (106 loc) · 4.93 KB

README.md

File metadata and controls

149 lines (106 loc) · 4.93 KB

macOS Multipass Docker

Step by step notes for installing Docker under macOS via Canonical's Multipass.

What this provides

  • Docker Engine (daemon).
  • docker CLI tool within the guest VM (technically not needed, but handy if working inside VM).
  • Installed docker and docker-compose CLI tools (with Bash completion) on the macOS host.

Installation

Install Multipass for macOS (obviously).

Next, launch a new Multipass virtual machine.

Note

Setting desired Multipass virtual machine name in MACHINE_NAME environment variable, used in all following command examples.

$ MACHINE_NAME="my-docker"
$ PATH_TO_PROJECTS="/path/to/projects"

$ multipass launch \
  --cloud-init ./cloud-init-docker.yaml \
  --name $MACHINE_NAME \
    22.04

$ multipass stop $MACHINE_NAME
$ multipass mount --type native \
  $PATH_TO_PROJECTS $MACHINE_NAME

$ multipass start $MACHINE_NAME
$ multipass info $MACHINE_NAME

# Name:           MACHINE_NAME
# State:          Running
# IPv4:           --

# Release:        Ubuntu 22.04.3 LTS
# Image hash:     9256911742f0 (Ubuntu 22.04 LTS)
# CPU(s):         --
# Load:           --
# Disk usage:     --
# Memory usage:   --
# Mounts:         /path/to/projects => /path/to/projects

Breaking this down:

  • Create new virtual machine using Ubuntu 22.04.
  • Configure VM using cloud-init-docker.yaml - which will install and configure Docker dependencies.
  • Stop the instance in order to create a mount to (path/to/projects) within the VM guest back to the macOS host. This is important for Dockerfile operations such as ADD - ensuring Docker Engine within the VM guest can successfully map files stored within the macOS host filesystem.
    • Note: using multipass mount --type native to create a native QEMU host mount, rather than the (slower) default of SSHFS.

Overview of tasks performed by cloud-init-docker.yaml:

  • The avahi-daemon provides a well-known hostname to the Multipass VM via mDNS/Bonjour from the host (e.g. your macOS).
  • A series of runcmd commands to install required Docker Engine packages.
  • An addition of a /etc/systemd/system/docker.service.d/httpapi.conf systemd unit drop-in, which starts the /usr/bin/dockerd daemon with the HTTP API listening on all networks.

Next, install docker and docker-compose CLI tools to the macOS host via cli-install.sh.

Note: script requires jq to be installed:

$ ./cli-install.sh

# Docker version 24.0.7, build afdd53b
# Docker Compose version v2.23.0

Finally, configure a DOCKER_HOST environment variable, allowing the docker CLI to locate Docker Engine running within the Multipass Ubuntu VM:

# first, ping VM to confirm it can be found from host
$ dns-sd -Gv4 "$MACHINE_NAME.local"

$ export DOCKER_HOST="tcp://$MACHINE_NAME.local:2375"
$ docker version

# Client:
#  Version:           24.0.7
#  API version:       1.43
#  etc.
#
# Server: Docker Engine - Community
#  Engine:
#   Version:          24.0.7
#   API version:      1.43 (minimum version 1.12)
#  etc.

Once proven working, DOCKER_HOST can be added to Dotfiles / ~/.bash_profile / etc.

Done!

Tips

Disable primary instance

Multipass has the concept of a primary instance, which is automatically used for commands such as start and shell. This behaviour can be somewhat undesirable - where it is preferred to use defined machine names against all multipass commands.

Luckily the primary instance mode can be disabled by setting an empty client.primary-name value:

$ multipass set client.primary-name=

the enablement of this mode can now be confirmed:

$ multipass start
Name argument or --all is required
Note: the primary instance is disabled.

$ multipass shell
The primary instance is disabled, please provide an instance name.

Restarting multipassd

If the Multipass service ever falls away, such as with the following message:

$ multipass list
list failed: cannot connect to the multipass socket

it can be restarted with the following commands:

$ sudo launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist
$ sudo launchctl load -w /Library/LaunchDaemons/com.canonical.multipassd.plist

Reference