Run macOS in Docker: Complete Linux Configuration and Deployment Guide

Prerequisites

Before starting, ensure you meet the following requirements:

1. Install Docker:

   • Make sure Docker Engine is installed on your system. You can install it using the following command (Ubuntu example):

     sudo apt update
     sudo apt install docker.io
     sudo systemctl start docker
     sudo systemctl enable docker

2. Required Devices:

   • Ensure the system supports /dev/kvm and /dev/net/tun devices.
   • You may need to add permissions by running:

     sudo chmod 666 /dev/kvm

3. Disk Space:

   • Prepare sufficient disk space (recommended at least 64GB) for storing macOS images and data.

Installation Steps

1. Pull Docker Image

Run the following command to pull the dockurr/macos image:

docker pull dockurr/macos

2. Run Docker Container

Use the following command to start the macOS container:

docker run -it --rm --name macos -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN -v "${PWD:-.}/macos:/storage" --stop-timeout 120 dockurr/macos

Parameter Explanation:

• -it: Run container in interactive mode.
• --rm: Automatically remove container after exit.
• --name macos: Container name is macos.
• -p 8006:8006: Map host port 8006 to container for web access.
• --device=/dev/kvm and --device=/dev/net/tun: Enable KVM and network devices.
• --cap-add NET_ADMIN: Grant container network management permissions.
• -v "${PWD:-.}/macos:/storage": Mount the macos folder in the current directory to /storage in the container for storing macOS data.
• --stop-timeout 120: Set container stop timeout to 120 seconds.

Optional Environment Variables:

• VERSION: Specify macOS version, default is macOS 13 (Ventura). Supported versions include:
  • 11 (Big Sur)
  • 12 (Monterey)
  • 13 (Ventura)
  • 14 (Sonoma)
  • 15 (Sequoia, some features like Apple account login not yet supported). Example:

  docker run -it --rm --name macos -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN -v "${PWD:-.}/macos:/storage" -e VERSION="ventura" --stop-timeout 120 dockurr/macos

3. Access via Web Browser

1. After starting the container, open your browser and visit http://localhost:8006.
2. You will enter the macOS installation interface.

4. Configure Disk

1. In the macOS installation interface, select Disk Utility.
2. Find the largest Apple Inc. VirtIO Block Media disk.
3. Click the Erase button to format the disk as APFS file system and name the disk (any name).
4. Close the Disk Utility window.

5. Install macOS

1. Click Reinstall macOS to start the installation process.
2. When prompted to select installation target, choose the disk you just formatted.
3. Wait for file copying to complete (may take some time depending on network and hardware performance).
4. After installation, set up your region, language, and account information.

6. Complete Setup

After installation, you will enter the macOS desktop environment. You can continue accessing macOS through the browser or connect to the container via VNC (port 5900).

VNC Connection (Optional):

• Use a VNC client (like VNC Viewer) to connect to localhost:5900.
• Ensure port 5900 (TCP and UDP) is mapped when starting the container:

  -p 5900:5900/tcp -p 5900:5900/udp

7. Enjoy macOS

After installation, you can run macOS in the Docker container and experience an almost native macOS system. Don’t forget to star the dockur/macos repository to support the developers!

Using Docker Compose (Optional)

If you prefer using Docker Compose, you can create a docker-compose.yml file with the following content:

services:
  macos:
    image: dockurr/macos
    container_name: macos
    environment:
      - VERSION=13
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
      - 5900:5900/tcp
      - 5900:5900/udp
    volumes:
      - ./macos:/storage
    restart: always
    stop_grace_period: 2m

After saving, run the following command to start the container:

docker-compose up -d

Important Notes

1. Legal Compliance:

   • This project only contains open-source code and does not distribute any copyrighted materials or bypass copyright protection measures.
   • According to Apple’s EULA, macOS can only run on Apple hardware. Running on non-Apple hardware may violate terms, please ensure compliant usage.

2. macOS Version Support:

   • Default installation is macOS 13 (Ventura).
   • macOS 15 (Sequoia) support is not yet complete and may not allow Apple account login.

3. Performance Optimization:

   • If you encounter KVM-related errors, try adding privileged: true in docker-compose.yml or add sudo before the docker run command.
   • Ensure the host has sufficient CPU and memory resources to support virtualization.

4. Storage Management:

   • Data is stored by default in the ./macos directory. You can change the storage location by modifying the -v parameter.
   • If you need more disk space, you can add the DISK_SIZE environment variable in docker-compose.yml (e.g., DISK_SIZE=128G).

5. Network Configuration:

   • The container supports connections via port 8006 (web access) and 5900 (VNC).
   • Ensure the firewall does not block these ports.

6. Acknowledgments:

   • This project thanks seitenca for contributions and OpenCore and KVM-OpenCore projects for support.

Troubleshooting

1. KVM Errors:

   • If the container startup shows KVM-related errors, check if the /dev/kvm device exists and has correct permissions:

     ls -l /dev/kvm
     sudo chmod 666 /dev/kvm

   • Ensure you’re not using Docker Desktop and your CPU supports virtualization (VT-x/AMD-V).

2. Port Conflicts:

   • If ports 8006 or 5900 are occupied, modify the port mapping in docker run or docker-compose.yml, for example -p 8080:8006.

3. Installation Failures:

   • Ensure stable network connection, macOS installation requires downloading large files.
   • Check if disk space is sufficient.

4. Performance Issues:

   • Increase CPU and memory resources allocated to the container (through Docker settings or resources configuration in docker-compose.yml).

Additional Resources

• GitHub Repository: https://github.com/dockur/macos
• Kubernetes Support: You can deploy macOS in Kubernetes using the following command:

  kubectl apply -f https://raw.githubusercontent.com/dockur/macos/refs/heads/master/kubernetes.yml

• Related Projects:
  • dockur/windows: Similar project for running Windows in Docker.
  • sickcodes/Docker-OSX: Another Docker project for running macOS.