Learn how to – How To Run macOS in Docker Container using Docker-OSX

Learn how to – How To Run macOS in Docker Container using Docker-OSX.

It is habitual that docker containers can be accessed using CLI processes with no Graphical interfaces at all. Did you know it is possible to run graphical applications such as Firefox, chrome e.t.c on docker using OS X?

Docker-OSX is a project that simplifies macOS installation using Docker containers on OSX-KVM. It allows one to install macOS Big Sur, Monterey desktop, Catalina or boot to the OSX shell.

The provided docker images are:

• macOS Catalina – sickcodes/docker-osx:latest(1.88GB)
• macOS Big Sur – sickcodes/docker-osx:big-sur(2.1GB)
• macOS Monterey – sickcodes/docker-osx:Monterey(2.08GB)
• OS X shell with a visual display – sickcodes/docker-osx:auto

There are also older versions:

• macOS Mojave – sickcodes/docker-osx:mojave(1.91GB)
• macOS High Sierra – sickcodes/docker-osx:high-sierra(1.91GB)

This project offers amazing features such as:

• Full auto mode: boot straight to OSX shell and even run commands as runtime arguments
• SSH on localhost:50922
• macOS Monterey VM on Linux!
• NC version on localhost:8888: the VNC version is in a separate directory due to the security risks involved with using VNC
• Xfvb headless mode
• Folder sharing
• Kubernetes Helm Chart.
• X11 Forwarding
• Use iPhone OSX KVM on Linux using usbfluxd!
• Create an ARMY of the same exact container using docker commit
• iMessage security research via serial number generator!

This guide will demonstrate how to run macOS in Docker Container using Docker-OSX.

Before You Begin

This guide will work best if the following are met:

• Hardware virtualization enabled in BIOS
• x86_64 KVM-capable host
• 20GB+++ disk space for bare minimum installation (50GB if using Xcode)
• At least 50 GBs for :auto (half for the base image, half for your runtime image
• Install Docker
• Install QEMU on the host system

#1. Install QEMU on Linux

KVM hypervisor is required to be able to run macOS in Docker containers. Below is a list of guides to help you install QEMU on your host machine:

• Install KVM Hypervisor on Ubuntu
• How To Install KVM Hypervisor on Debian
• How To Install KVM on RHEL 8 / CentOS 8
• How To Install KVM on Fedora

Once installed, add your user to the kvm group.

sudo usermod -aG kvm $USER

#2. Install Docker on Linux

This guide requires one to have the Docker engine installed. If you haven’t use the below guide:

• How To Install Docker CE on Linux Systems

Add your system user to the docker group.

sudo usermod -aG docker $USER
newgrp docker

Start and enable docker:

sudo systemctl start docker && sudo systemctl enable docker

#3. Run macOS in Docker Containers

Now proceed and run the preferred macOS distribution in docker containers. There are several environment variables one can use.

• macOS Big Sur

You can customize the WIDTH and HEIGHT to match your desired resolution.

docker run -it 
    --device /dev/kvm 
    -p 50922:10022 
    -e DEVICE_MODEL="iMacPro1,1" 
    -e WIDTH=1600 
    -e HEIGHT=900 
    -v /tmp/.X11-unix:/tmp/.X11-unix 
    -e "DISPLAY=${DISPLAY:-:0.0}" 
    -e GENERATE_UNIQUE=true 
    -e MASTER_PLIST_URL=https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom.plist 
    sickcodes/docker-osx:big-sur

• macOS Catalina

docker run -it 
    --device /dev/kvm 
    -p 50923:10022 
    -e GENERATE_UNIQUE=true 
    -e DEVICE_MODEL="iMacPro1,1" 
    -e WIDTH=1600 
    -e HEIGHT=900 
    -v /tmp/.X11-unix:/tmp/.X11-unix 
    -e "DISPLAY=${DISPLAY:-:0.0}" 
    sickcodes/docker-osx:latest

• macOS Monterey

docker run -it 
    --device /dev/kvm 
    -p 50924:10022 
    -e GENERATE_UNIQUE=true 
    -e DEVICE_MODEL="iMacPro1,1" 
    -e WIDTH=1600 
    -e HEIGHT=900 
    -v /tmp/.X11-unix:/tmp/.X11-unix 
    -e "DISPLAY=${DISPLAY:-:0.0}" 
    -e GENERATE_UNIQUE=true 
    -e MASTER_PLIST_URL='https://raw.githubusercontent.com/sickcodes/osx-serial-generator/master/config-custom.plist' 
    sickcodes/docker-osx:monterey

• macOS High Sierra

docker run -it 
    --device /dev/kvm 
    -p 50922:10022 
    -v /tmp/.X11-unix:/tmp/.X11-unix 
    -e "DISPLAY=${DISPLAY:-:0.0}" 
    sickcodes/docker-osx:high-sierra

• macOS Mojave

docker run -it 
    --device /dev/kvm 
    -p 50922:10022 
    -v /tmp/.X11-unix:/tmp/.X11-unix 
    -e "DISPLAY=${DISPLAY:-:0.0}" 
    sickcodes/docker-osx:mojave

More customization options can be made to the container such as:

• RAM, Cores, SMP

The default RAM used is 3GB, but you can increase this depending on the available RAM.

$ free -mh
              total        used        free      shared  buff/cache   available
Mem:          20.5Gi       5.8Gi        5.8Gi     322Mi       1.6Gi       10.1Gi
Swap:         12.0Gi       922Mi       1.1Gi

Adjust the RAM, Cores, SMP using the flags:

    -e RAM=6 
    -e SMP=4 
    -e CORES=4 

• Resolution

The desired resolution can be set using the Height and width for example 800×600 will be:

    -e WIDTH=800 
    -e HEIGHT=600 

• Mounting Physical disks

You can mount a physical Mac OSX disk. First export the variables:

OSX_IMAGE="${PWD}/mac_hdd_ng_xcode_bigsur.img"
DISK_TWO="${PWD}/mount_me.img"

Now capture the disk in docker using the -v flag.

    -v "${OSX_IMAGE}":/image 
    -v "${DISK_TWO}":/disktwo 

#4. Configure your macOS Installation

The download will take a few minutes. Once complete, you will see this popup.

Select macOS Base System and proceed. The system will initialize a shown.

Format the largest QEMU Disk

Using the Disk Utility format the largest QEMU Disk.

For this case, the largest disk is 274.88 GB. Once selected, click on erase.

Provide a name for the disk and click Erase

Once complete, you will see this.

#5. Install macOS on the Virtual Machine.

Close the disk utility and now click on Reinstall macOS Big Sur or whatever distribution for your case.

Click continue to start the installation.

Agree to the License terms.

Select the erased disk. For my case, I named it BigSur.

Sit back and wait for the installation to complete.

Once complete, the macOS VM will reboot. Select the macOS Installer entry here.

On completion, the entry above will be updated to Big Sur. Now you can boot into your new installation by clicking on it.

Proceed and make the post-installation configurations such as:

Setting our country or region

Set the preferred language

Set apple ID, create a user account and password e.t.c

Mount/Share directories, files

The easiest way to achieve this is by using sshfs

First, create the directory to be shared/mounted.

sudo mkdir /mnt/osx
sudo chmod -R 777 /mnt/osx

Now use sshfs to mount/share the directory:

sshfs user@localhost:/ -p 50922 /mnt/osx

After a few seconds, you will have the directory mounted.

#6. Manage the macOS Virtual Machine

The macOS virtual machine can be managed using docker. To start it, get the container ID with the command:

$ docker ps -a
CONTAINER ID   IMAGE                          COMMAND                  CREATED        STATUS                      PORTS     NAMES
9ce4b501ce82   sickcodes/docker-osx:big-sur   "/bin/bash -c 'sudo …"   14 hours ago   Exited (0) 22 minutes ago             loving_poincare

Use the container ID to start the VM.

docker start Container_ID/Name

You can also configure the VM to run as a system service by creating a service file.

sudo vim /etc/systemd/system/BigSur_container.service

Add the below lines to the file:

[Unit]
Description=Semaphore container

[Service]
Restart=always
ExecStart=/usr/bin/docker start -a Container_ID/Name
ExecStop=/usr/bin/docker stop -t 2 Container_ID/Name

[Install]
WantedBy=local.target

Remember to replace the Container_ID/Name in the file as required. Reload the system daemon.

sudo systemctl daemon-reload

Now you can start the container just like any other system service:

sudo systemctl start BigSur_container

Check the status of the container.

$ systemctl status BigSur_container
● BigSur_container.service - Semaphore container
     Loaded: loaded (/etc/systemd/system/BigSur_container.service; disabled; vendor preset: >
     Active: active (running) since Wed 2022-06-01 13:23:21 EAT; 13s ago
   Main PID: 7368 (docker)
      Tasks: 8 (limit: 9070)
     Memory: 18.0M
     CGroup: /system.slice/BigSur_container.service
             └─7368 /usr/bin/docker start -a 9ce4b501ce82

Jun 01 13:23:39 home docker[7368]: + for f in /sys/block/sd*/device/timeout
Jun 01 13:23:39 home docker[7368]: + echo 300

To stop the container run:

sudo systemctl stop BigSur_container

To remove a Docker-OSX container, first, get the list of available containers.

docker container ls -a

Stop the container.

docker container stop ID_or_Name
docker container rm ID_or_Name

Remove images:

docker image ls

Then remove the identified image:

docker image rm Image_ID

Closing Thoughts

That marks the end of this guide on how to run macOS in Docker Container using Docker-OSX. I hope learned a lot from this guide.

Related posts:

• Install macOS Big Sur & Catalina on VirtualBox
• How to install gcloud GCP cli on Apple M1 macOS
• Install and Use Nu Shell on Linux | macOS
• Install IINA – Best video player for macOS