Motivation

Docker recently updated its terms making the Docker Desktop for macOS and Windows free only for personal use. Any business with more than 250 employees or more than $10 million annual revenue needs to buy its Docker Business subscription. For me, the Docker Desktop was already a hit and a miss. It was great when it worked but a pain to troubleshoot when it did not. Also, it does not bode well when they make software based on open source tools paid after it was free for a long time. Now is the time to find an alternative for this.

PhotonOS

If you read my previous post on PhotonOS , you would know how impressed I was with it. This is a perfect use case for such a lightweight operating system, being targetted at container workloads. So that’s what we will use to create this alternative for the Docker Desktop. I will go through two hypervisor configurations, Oracle VirtualBox (free) and VMware Fusion Pro (not free, needs a license). Before proceeding, download the Minimal ISO x86_64 PhotonOS ISO from Github . For this setup to also work over VPN connections, port forwarding is necessary. Otherwise, the DOCKER_HOST can point directly to the VM’s IP address to simplify configuration.

Installing PhotonOS: Oracle VirtualBox

VirtualBox is much easier in terms of configuring port forwards and shared folders. Follow the steps below to get started.

  1. Start by creating a new VM. Provide it a name and select Linux/Linux 2.6/3.x/4.x (64-bit)

  2. Select the Memory size. I prefer to keep this at 1 or 2 GB

  3. Create a virtual hard disk now. Accept the defaults of VDI and dynamically size by hitting Continue

  4. Select the size of the hard disk. I prefer a 20G disk that I can increase if need be

  5. Once done, click on Settings for the new VM

  6. Under Storage, Select Empty under Controller: IDE. Click on the CD icon beside the Optical drive option to Choose a disk file and select the photonOS minimal ISO downloaded before

  7. Under Network, expand Advanced and click on Port Forwarding. Click on the green + icon to add a new forwarding for the Docker API, select TCP protocol, leave the Host IP empty, enter 2375 for the Host Port, leave the Guest IP empty, and enter 2375 for the Guest Port. Click OK to complete the configuration

    VirtualBox NAT Port forwarding

  8. Under Shared Folders, click the green + icon to add a new share and select your home folder for the Folder Path. Copy this folder path and paste it in the Mount point section. Enable Auto-mount and click OK

    VirtualBox Shared Folders

  9. Continue to follow the common installation section

Installing PhotonOS: VMWare Fusion Pro

VMware Fusion Pro does not make it easy to customize shared folders, create static IP configs and add port forwarding we need. Follow step 0 to create a new network that we will customize later and proceed.

  1. Click on VMware Fusion in the menu bar and select Preferences
    1. Under Network, click the lock icon to unlock the settings
    2. Click on the + icon to add a new network.
    3. Enable Allow virtual machines on this network to connect to external networks (using NAT)
    4. Apply the changes. Note down the network adapter name needed for post-installation. It is of the format vmnetX. For me, it was vmnet3
  2. Now start by creating a new virtual machine by File > New. Drag and drop the downloaded ISO image here and select continue
  3. For the boot firmware, select UEFI, but do not select UEFI Secure Boot as the keys needed for it won’t be enrolled
  4. In the next page, click on Customize Settings, give the VM a name and accept or change where the VM would be stored. Once done, click Finish
  5. Now, you would see a VM Settings window show up. If not, click on the Virtual Machine on the menu bar and click on Settings
  6. Here, we need to configure a couple of things

    1. In Sharing, enable Shared Folders, and add a new share. This will be your Home directory, so that you can mount files from macOS to docker. Let the permission be Read/Write

      VMware Fusion Pro Shared folders

    2. In Processors & Memory, change the settings based on your usage. I prefer to allocate two processor cores and 1 or 2 GB of Memory

    3. In Network Adapter, select the adapter created in step 0. For me, it was vmnet3

    4. In Hard Disk (SCSI), increase the Disk size. All the docker images that we pull are stored here. I prefer to keep it at 20G and increase it if needed. Remember to hit Apply here

    5. In Advanced, enable the checkbox to Disable Side Channel Mitigations. See the VMware KB article for more details

  7. Continue to follow the common installation section

Installing PhotonOS: Common

Power on the VM and hit Enter to begin the installation.

  1. Hit Enter to Accept the Licence Agreement
  2. Hit Enter to Auto Select the disk partitions
  3. Hit Enter to Proceed with automatic network configuration
  4. If using VMware Fusion, you will see an additional configuration choice. Here, you can choose the VMware hypervisor optimized kernel
  5. Provide a hostname. I keep it simple, for example: photon-docker
  6. Provide a root password to use later while logging in
  7. Select Yes to continue with the installation

This will be done in less than a minute. It took me just 20 seconds! Once done, hit enter to reboot and login with root and the password set in the previous step to continue with configuring PhotonOS if using VirtualBox or follow post installation steps for VMware Fusion Pro .

Post-installation: VMware Fusion Pro

Once the installation of Photon OS is complete, we need to configure a static IP address for the VM to enable port forwarding. Power off the VM and follow the steps below.

  1. From Virtual Machine Settings (Virtual Machine > Settings), head over to Network Adapter

  2. Expand Advanced options to copy the MAC address shown

  3. From a terminal, run the below commands to open up an editor. Remember to replace vmnetX with the name noted down before installation

    1
2

    cd /Library/Preferences/VMware\ Fusion/vmnetX
sudo nano dhcpd.conf

  4. Find the section which shows the subnet. A sample is shown below. Change the last octet to choose a static IP for your VM. Keep the number between 3 and 127 since the rest of the range is used by DHCP. I choose 172.16.88.3 in my example

    1
2
3

    subnet 172.16.88.0 netmask 255.255.255.0 {
    ...
}

  5. Scroll down to the very end of the file and add the text shown below. Replace the MAC address 00:00:00:00:00:00 with the MAC address of the VM copied in step 2. Replace the IP address 172.16.88.3 with an IP address chosen in step 4

    1
2
3
4

    host PhotonOS {
    hardware ethernet 00:00:00:00:00:00;
    fixed-address 172.16.88.3;
}

    Save and exit nano by pressing the sequence Ctrl+X, Y, Enter

  6. Restart VMware Fusion Pro by quitting the app and relaunching it for the DHCP configuration changes to take effect

  7. Click on VMware Fusion > Preferences. Under Network, select the one created before. In my case, vmnet3. Click the lock icon to edit the configuration

  8. Click + to add an entry in the Port Forwarding table for the Docker API. Host port is 2375, Type is TCP, Virtual machine IP address is the one chosen in step 4 and the Virtual machine port is 2375. Provide a description and hit OK

    VMware Fusion Pro Port Forward

  9. Add any further ports you might need to expose from docker. You can do this any time, even when the VM is powered on. I added 8080 as I most commonly publish services to port 8080

  10. Power on the VM and login with root credentials

  11. To make sharing as seamless are possible, let us configure a soft link for the share we created earlier

    1
2
3
4
5

    ln -s /mnt/hgfs /Users

# This command should show your username as a mounted share and show your files in the home folder
ls /Users
ls /Users/*

  12. Continue with Configuring PhotonOS .

Configuring PhotonOS

To configure docker to listen on the TCP port along with the unix socket at /var/run/docker.sock, run the commands below from the PhotonOS console

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# Disable firewall to allow ports to be accessed
systemctl disable --now iptables

# Enable docker service to start on boot
systemctl enable --now docker

# Set docker daemon config JSON to listen on Unix socket and TCP port 2375.
cat <<EOF > /etc/docker/daemon.json
{
    "hosts": ["fd://", "tcp://0.0.0.0:2375"]
}
EOF

# Remove listen only on Unix socket configuration from the docker service file.
sed 's| -H fd://||g' -i /usr/lib/systemd/system/docker.service

# Reload systemd units to pick up the changes made to the docker service
systemctl daemon-reload

# Restart the docker service
systemctl restart docker

To validate if this configuration change worked, run the below command. It should correctly show the docker version without any errors.

1

DOCKER_HOST="tcp://127.0.0.1:2375" docker version

Configuring the macOS host

You should now be able to use docker from your macOS terminal! To do so, open the Terminal on macOS, install the docker cli from homebrew and add the environment variable to be used at startup using the commands below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# Install docker and docker-compose cli
# Note that this is not installing the docker cask which installs docker desktop
brew install docker docker-compose

# Edit the .zshrc/.bashrc to export the DOCKER_HOST on startup
nano ~/.zshrc

# Add this line at the very end of the file
export DOCKER_HOST=tcp://127.0.0.1:2375

# Make it take effect immediately
source ~/.zshrc

# Check if it all works!
docker version
docker run --rm -v ~/:/hostuser alpine:latest ls /hostuser

And that’s it! You have a fully functioning docker desktop replacement, batteries included. Just remember to add more port forwards if you need to expose services from docker containers to be accessible from the host.