@ -6,25 +6,53 @@ Run Mac OS X in Docker with near-native performance! X11 Forwarding! iMessage se
## Author
## Author
This project is maintained by [Sick.Codes](https://sick.codes/) [(Twitter)](https://twitter.com/sickcodes)
This project is maintained by [Sick.Codes](https://sick.codes/). [(Twitter)](https://twitter.com/sickcodes)
Additional credits can be found here: https://github.com/sickcodes/Docker-OSX/blob/master/CREDITS.md
Additional credits can be found here: https://github.com/sickcodes/Docker-OSX/blob/master/CREDITS.md
Additionally, comprehensive list of all contributors can be found here: https://github.com/sickcodes/Docker-OSX/graphs/contributors
Additionally, comprehensive list of all contributors can be found here: https://github.com/sickcodes/Docker-OSX/graphs/contributors
Special thanks to [@kholia](https://twitter.com/kholia) for maintaining the upstream project, which Docker-OSX is built on top of: [OSX-KVM](https://github.com/kholia/OSX-KVM)
Special thanks to [@kholia](https://twitter.com/kholia) for maintaining the upstream project, which Docker-OSX is built on top of: [OSX-KVM](https://github.com/kholia/OSX-KVM).
## Technical details
**Current large image size:** 17.5GB
The images (excluding `:naked`) launch a container with an existing installation with a couple of premade configurations. This special image was developed by [Sick.Codes](https://sick.codes):
- username: `user`, password: `alpine`
- ssh enabled (`localhost:50922`)
- vnc enabled (`localhost:8888`)
- auto-updates disabled
- serial number generators!
- x11 forwarding is enabled
- runs on top of QEMU + KVM
- supports big sur, custom images, xfvb headless mode
- you can clone your container with `docker commit`
### Requirements
- at least 50 GBs (half for the base image, half for your runtime image
- virtualization should be enabled in your bios settings
- a kvm-capable host
### To be done
- documentation for security researchers
- gpu acceleration
- support for virt-manager
## Docker
## Docker
Images built on top of the contents of this repository are also available on **Docker Hub** for convenience: https://hub.docker.com/r/sickcodes/docker-osx
Images built on top of the contents of this repository are also available on **Docker Hub** for convenience: https://hub.docker.com/r/sickcodes/docker-osx
A comprehensive list of the available Docker images and their intended purpose can be found in the [Instructions](README.md#Instructions)
A comprehensive list of the available Docker images and their intended purpose can be found in the [Instructions](README.md#Instructions).
## Kubernetes
## Kubernetes
Docker-OSX supports Kubernetes.
Docker-OSX supports Kubernetes.
Kubernetes Helm Chart & Documentation can be found under the [helm directory](helm/README.md)
Kubernetes Helm Chart & Documentation can be found under the [helm directory](helm/README.md).
Thanks [cephasara](https://github.com/cephasara) for contributing this major contribution.
Thanks [cephasara](https://github.com/cephasara) for contributing this major contribution.
@ -40,7 +68,7 @@ Feel free to open an [issue](https://github.com/sickcodes/Docker-OSX/issues/new/
Before you open an issue, however, please check the [closed issues](https://github.com/sickcodes/Docker-OSX/issues?q=is%3Aissue+is%3Aclosed) and confirm that you're using the latest version of this repository — your issues may have already been resolved!
Before you open an issue, however, please check the [closed issues](https://github.com/sickcodes/Docker-OSX/issues?q=is%3Aissue+is%3Aclosed) and confirm that you're using the latest version of this repository — your issues may have already been resolved!
@ -58,6 +86,10 @@ In case you're interested, contact [@sickcodes on Twitter](https://twitter.com/s
Docker-OSX is licensed under the [GPL v3](LICENSE). Contributions are welcomed and immensely appreciated.
Docker-OSX is licensed under the [GPL v3](LICENSE). Contributions are welcomed and immensely appreciated.
### Other cool Docker/QEMU based projects
- [Run iOS in a Docker container with Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS) - [https://github.com/sickcodes/Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS)
## Disclaimer
## Disclaimer
Product names, logos, brands and other trademarks referred to within this project are the property of their respective trademark holders. These trademark holders are not affiliated with our repository in any capacity. They do not sponsor or endorse our materials.
Product names, logos, brands and other trademarks referred to within this project are the property of their respective trademark holders. These trademark holders are not affiliated with our repository in any capacity. They do not sponsor or endorse our materials.
@ -127,22 +159,11 @@ Use `docker commit`, copy the ID, and then run `docker start -ai <Replace this w
[Extract the .img file](https://github.com/sickcodes/Docker-OSX#backup-the-disk-wheres-my-disk), and then use that [.img file with :naked](https://github.com/sickcodes/Docker-OSX#quick-start-own-image-naked-container-image)
[Extract the .img file](https://github.com/sickcodes/Docker-OSX#backup-the-disk-wheres-my-disk), and then use that [.img file with :naked](https://github.com/sickcodes/Docker-OSX#quick-start-own-image-naked-container-image)
# Technical details
#### Further examples
**Current large image size:** 17.5GB
The images (excluding `:naked`) launch a container with an existing installation with a couple of premade configurations. This special image was developed by [Sick.Codes](https://sick.codes):
- SSH enabled
- username is `user`
- password is `alpine`
- auto-updates are disabled
## Requirements
You will need around *50 GB* of space to run this image: half for the base image + half for your runtime image.
Apart from the previous examples, there's a myriad of other potential use cases that can work perfectly with Docker-OSX.
If you run out of space, you can delete all your old Docker images/history/cache by simply deleting `/var/lib/docker`, and restarting `dockerd`.
### Run Mac OS X
```bash
```bash
docker pull sickcodes/docker-osx:auto
docker pull sickcodes/docker-osx:auto
@ -157,7 +178,6 @@ docker run -it \
```
```
```bash
```bash
docker pull sickcodes/docker-osx:auto
docker pull sickcodes/docker-osx:auto
# boot directly into a real OS X shell with a visual display [NOT HEADLESS]
# boot directly into a real OS X shell with a visual display [NOT HEADLESS]
@ -167,10 +187,25 @@ docker run -it \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e "DISPLAY=${DISPLAY:-:0.0}" \
sickcodes/docker-osx:auto
sickcodes/docker-osx:auto
```
### Download the image manually and use it in Docker
This is a particularly good way for downloading the container, in case Docker's CDN (or your connection) happens to be slow.
### Pre-built Image + Arbitrary Command Line Arguments.
### Use a pre-built image + arbitrary command line arguments.
```bash
```bash
docker pull sickcodes/docker-osx:auto
docker pull sickcodes/docker-osx:auto
@ -187,7 +222,20 @@ docker run -it \
# Boots in a minute or two!
# Boots in a minute or two!
```
```
### Restart an auto container
### Run Mac OS X headlessly with a custom image
This is particularly helpful for CI/CD pipelines.
```bash
# run your own image headless + SSH
docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v "${PWD}/mac_hdd_ng.img:/image" \
sickcodes/docker-osx:naked
```
### Restart a container that starts automatically
Containers that use `sickcodes/docker-osx:auto` can be stopped while being started.
Containers that use `sickcodes/docker-osx:auto` can be stopped while being started.
@ -199,17 +247,18 @@ docker ps -a
docker start -ai -i <ReplacethiswithyourID>
docker start -ai -i <ReplacethiswithyourID>
```
```
### Quick Start Own Image (naked container image)
### Quick Start your own image (naked container image)
This is my favourite container. You can supply an existing disk image as a docker command line argument.
Pull images out using `sudo find /var/lib/docker -size +10G | grep mac_hdd_ng.img`
This is my favourite container. You can supply an existing disk image as a Docker command line argument.
Supply your own local image with `-v "${PWD}/mac_hdd_ng.img:/image"` and use `sickcodes/docker-osx:naked`
- Pull images out using `sudo find /var/lib/docker -size +10G | grep mac_hdd_ng.img`
- Naked image is for booting any existing .img file, e.g in the current working directory (`$PWD`)
- Supply your own local image with the command argument `-v "${PWD}/mac_hdd_ng.img:/image"` and use `sickcodes/docker-osx:naked` when instructing Docker to create your container.
- By default, this image has a variable called `NOPICKER` which is `"true"`. This skips the disk selection menu. Use `-e NOPICKER=false` or any other string than the word `true` to enter the boot menu. This lets you use other disks instead of skipping the boot menu, e.g. recovery disk or disk utility.
- Naked image is for booting any existing .img file, e.g in the current working directory (`$PWD`)
- By default, this image has a variable called `NOPICKER` which is `"true"`. This skips the disk selection menu. Use `-e NOPICKER=false` or any other string than the word `true` to enter the boot menu.
This lets you use other disks instead of skipping the boot menu, e.g. recovery disk or disk utility.
```bash
```bash
docker pull sickcodes/docker-osx:naked
docker pull sickcodes/docker-osx:naked
@ -235,55 +284,7 @@ docker run -it \
sickcodes/docker-osx:naked
sickcodes/docker-osx:naked
```
```
### Fully Headless, using a custom image, for CI/CD
### Run the original version of Docker-OSX
```bash
# run your own image headless + SSH
docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v "${PWD}/mac_hdd_ng.img:/image" \
sickcodes/docker-osx:naked
```
# Features In Docker-OSX v4
- `sickcodes/docker-osx:big-sur` - original base recovery image for latest OS (safe)
- Serial number generators. [See below or ./custom](https://github.com/sickcodes/Docker-OSX/tree/master/custom)
- Full auto mode: boot straight to OS X shell and even run commands as runtime arguments!
- `sickcodes/docker-osx:latest` - original base recovery image (safe)
- `sickcodes/docker-osx:naked` - supply your own .img file (safe)
- `sickcodes/docker-osx:auto` - Large docker image that boots to OS X shell (must trust @sickcodes)
- Supply your own image using `-v "${PWD}/disk.img:/image"`
- [OSX-KVM](https://github.com/kholia/OSX-KVM) inside a Docker container!
- X11 Forwarding
- SSH on `localhost:50922`
- QEMU + KVM!
- VNC version on `localhost:8888` [vnc version is inside a separate directory, there are security risks involved with using VNC, see insid the Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/master/vnc-version/Dockerfile)
- Create an ARMY of the same exact container using `docker commit`
[Run iOS in a Docker with Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS) - [https://github.com/sickcodes/Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS)
# Run Docker-OSX (Original Version)
```bash
```bash
@ -296,12 +297,9 @@ docker run -it \
-e "DISPLAY=${DISPLAY:-:0.0}" \
-e "DISPLAY=${DISPLAY:-:0.0}" \
sickcodes/docker-osx:latest
sickcodes/docker-osx:latest
# press ctrl G if your mouse gets stuck
# press CTRL + G if your mouse gets stuck
# scroll down to troubleshooting if you have problems
# scroll down to troubleshooting if you have problems
# need more RAM and SSH on localhost -p 50922?
# need more RAM and SSH on localhost -p 50922?
```
```
# Run but enable SSH in OS X (Original Version)!
# Run but enable SSH in OS X (Original Version)!
@ -316,11 +314,10 @@ docker run -it \
sickcodes/docker-osx:latest
sickcodes/docker-osx:latest
# turn on SSH after you've installed OS X in the "Sharing" settings.
# turn on SSH after you've installed OS X in the "Sharing" settings.
ssh fullname@localhost -p 50922
ssh user@localhost -p 50922
```
```
# Autoboot into OS X after you've installed everything
### Autoboot into OS X after you've installed everything
You can use `-e NOPICKER=true`.
You can use `-e NOPICKER=true`.
@ -422,9 +419,12 @@ docker run \
newImageName
newImageName
```
```
# Troubleshooting
## Troubleshooting
### LibGTK - Permission denied
Thanks [@raoulh](https://github.com/raoulh) and [@arsham](https://github.com/arsham) for contributing this section.
PulseAudio for sound (note neither [AppleALC](https://github.com/acidanthera/AppleALC) and varying [`alcid`](https://dortania.github.io/OpenCore-Post-Install/universal/audio.html) or [VoodooHDA-OC](https://github.com/chris1111/VoodooHDA-OC) have [codec support](https://osy.gitbook.io/hac-mini-guide/details/hda-fix#hda-codec) though [IORegistryExplorer](https://github.com/vulgo/IORegistryExplorer) does show the controller component working):
### Use PulseAudio for sound
Note: [AppleALC](https://github.com/acidanthera/AppleALC), [`alcid`](https://dortania.github.io/OpenCore-Post-Install/universal/audio.html) and [VoodooHDA-OC](https://github.com/chris1111/VoodooHDA-OC) do not have [codec support](https://osy.gitbook.io/hac-mini-guide/details/hda-fix#hda-codec). However, [IORegistryExplorer](https://github.com/vulgo/IORegistryExplorer) does show the controller component working.
```bash
```bash
docker run \
docker run \
@ -453,7 +455,8 @@ docker run \
sickcodes/docker-osx
sickcodes/docker-osx
```
```
PulseAudio debugging:
#### PulseAudio debugging
```bash
```bash
docker run \
docker run \
--device /dev/kvm \
--device /dev/kvm \
@ -464,7 +467,9 @@ docker run \
sickcodes/docker-osx pactl list
sickcodes/docker-osx pactl list
```
```
Alternative run, thanks @roryrjb
#### Alternative soltuion
Thanks [@roryrjb](https://github.com/roryrjb) for contributing this section.
```bash
```bash
docker run \
docker run \
@ -477,39 +482,43 @@ docker run \
sickcodes/docker-osx
sickcodes/docker-osx
```
```
Check if your hardware virt is on
### Routine checks
#### Confirm that your CPU supports virtualization
```bash
```bash
egrep -c '(svm|vmx)' /proc/cpuinfo
egrep -c '(svm|vmx)' /proc/cpuinfo
```
```
Try adding yourself to the docker group
#### Try adding yourself to the docker group
```bash
```bash
sudo usermod -aG docker "${USER}"
sudo usermod -aG docker "${USER}"
```
```
Turn on docker daemon
#### Enable docker daemon
```bash
```bash
# run ad hoc
# enable it in systemd
sudo systemctl enable --now docker
# or run ad hoc
sudo dockerd
sudo dockerd
# or daemonize it
# or daemonize it
sudo nohup dockerd &
sudo nohup dockerd &
# or enable it in systemd
sudo systemctl enable --now docker
```
```
# How to Forward Additional Ports from the guest.
#### Forward additional ports (nginx)
This is how it visually looks:
It's possible to forward additional ports depending on your needs. In this example, we're going to use Mac OS X to host nginx in a way that looks like this:
@ -539,13 +549,11 @@ You can string multiple statements, for example:
-p 10043:10043 \
-p 10043:10043 \
```
```
# How to Enable Network Forwarding
### Enable IPv4 forwarding for bridged network connections
Allow ipv4 forwarding for bridged networking connections:
This is not required for LOCAL installations and may cause containers behind [VPN's to leak host IP](https://sick.codes/cve-2020-15590/).
This is not required for LOCAL installations and may [cause the host to leak your IP, even if you're using a VPN in the container](https://sick.codes/cve-2020-15590/).
If you are connecting to a REMOTE Docker-OSX, e.g. a "Mac Mini" in a datacenter, then this may boost networking:
However, if you're trying to connect to an instance of Docker-OSX remotely (e.g. an instance of Docker-OSX hosted in a datacenter), this may improve your performance:
```bash
```bash
# enable for current session
# enable for current session
@ -560,36 +568,15 @@ sudo tee -a /etc/sysctl.conf <<EOF
net.ipv4.ip_forward = 1
net.ipv4.ip_forward = 1
EOF
EOF
# OR edit manually
# or edit manually with the editor of your choice
nano /etc/sysctl.conf || vi /etc/sysctl.conf || vim /etc/sysctl.conf
nano /etc/sysctl.conf || vi /etc/sysctl.conf || vim /etc/sysctl.conf
# now reboot
# now reboot
```
```
# How to install Docker if you don't have Docker already
### Fedora: No internet connectivity with a bridged network
```bash
Fedora's default firewall settings may prevent Docker's network interface from reaching the internet. In order to reoslve this, you will need to whitelist the interface in your firewall:
# you can move (mv) it somewhere, using cp can take loads of disk space
sudo mv somedir/mac_hdd_ng.img .
```
# Use an Old Docker-OSX Disk in a Fresh Container (Replication)
[Use the sickcodes/docker-osx:naked image.](https://github.com/sickcodes/Docker-OSX/tree/master#quick-start-own-image)
# Internet Speeds
### FAST internet
`-e NETWORKING=vmxnet3`
`-e NETWORKING=vmxnet3`
### SLOW internet
#### Slow internet connectivity
`-e NETWORKING=e1000-82545em`
`-e NETWORKING=e1000-82545em`
# DESTROY: Wipe old images to free disk space
The easiest way to clean out your entire Docker (ALL images, layers, and containers) is to `sudo rm -rf /var/lib/docker`
### I'd like to use SPICE instead of VNC
This is useful for getting disk space back.
Optionally, you can enable the SPICE protocol, which allows you to use `remote-viewer` to access it rather than VNC.
It will delete ALL your old (and new) docker containers.
Note: `-disable-ticketing` will allow unauthenticated access to the VM. See the [spice manual](https://www.spice-space.org/spice-user-manual.html) for help setting up authenticated access ("Ticketing").
```bash
```bash
# WARNING deletes all old images, but saves disk space if you make too many containers
docker run \
# The following command will make your containers RIP
Then simply do `remote-viewer spice://localhost:3001` and add `--spice-debug` for debugging.
## How to reduce the size of the image
* Start up the container as usual, and remove unnecessary files. A useful way
### CI/CD Related Improvements
#### Tips for reducing the size of the image
- Start the container as usual, and remove unnecessary files. A useful way
to do this is to use `du -sh *` starting from the `/` directory, and find
to do this is to use `du -sh *` starting from the `/` directory, and find
large directories where files can be removed. E.g. unnecessary cached files,
large directories where files can be removed. E.g. unnecessary cached files,
Xcode platforms, etc.
Xcode platforms, etc.
* Once you are satisfied with the amount of free space, enable trim with `sudo trimforce enable`, and reboot.
- Once you are satisfied with the amount of free space, enable trim with `sudo trimforce enable`, and reboot.
* Zero out the empty space on the disk with `dd if=/dev/zero of=./empty && rm -f empty`
- Zero out the empty space on the disk with `dd if=/dev/zero of=./empty && rm -f empty`
* Shut down the VM and copy out the qcow image with `docker cp stoppedcontainer:/home/arch/OSX-KVM/mac_hdd_ng.img .`
- Shut down the VM and copy out the qcow image with `docker cp stoppedcontainer:/home/arch/OSX-KVM/mac_hdd_ng.img .`
* Run `qemu-img check -r all mac_hdd_ng.img` to fix any errors.
- Run `qemu-img check -r all mac_hdd_ng.img` to fix any errors.
* Run `qemu-img convert -O qcow2 mac_hdd_ng.img deduped.img` and check for errors again
- Run `qemu-img convert -O qcow2 mac_hdd_ng.img deduped.img` and check for errors again
* OPTIONAL: Run `qemu-img convert -c -O qcow2 deduped.img compressed.img` to further compress the image. This may reduce the runtime speed though, but it should reduce the size by roughly 25%.
- **OPTIONAL:** Run `qemu-img convert -c -O qcow2 deduped.img compressed.img` to further compress the image. This may reduce the runtime speed though, but it should reduce the size by roughly 25%.
* Check for errors again, and build a fresh docker image. E.g. with this Dockerfile
- Check for errors again, and build a fresh docker image. E.g. with this Dockerfile
First make sure [autoboot is enabled](#autoboot-into-osx-after-youve-installed-everything)
First make sure [autoboot is enabled](#autoboot-into-osx-after-youve-installed-everything)
Next, you will want to set up SSH to be automatically started.
Next, you will want to set up SSH to be automatically started.
@ -687,25 +658,9 @@ Then run it with these arguments.
mycustomimage
mycustomimage
```
```
Optionally, you can enable the SPICE protocol, which allows you to use `remote-viewer` to access it rather than VNC.
## Setting the appropriate mirrors when building locally
Note: `-disable-ticketing` will allow unauthenticated access to the VM. See the [spice manual](https://www.spice-space.org/spice-user-manual.html) for help setting up authenticated access ("Ticketing").
@ -1101,7 +1052,7 @@ You should see the device show up when you do `system_profiler SPUSBDataType` in
Important Note: this will cause the host system to lose access to the USB device while the VM is running!
Important Note: this will cause the host system to lose access to the USB device while the VM is running!
## What is `${DISPLAY:-:0.0}`?
#### What is `${DISPLAY:-:0.0}`?
`$DISPLAY` is the shell variable that refers to your X11 display server.
`$DISPLAY` is the shell variable that refers to your X11 display server.
@ -1119,12 +1070,14 @@ You can also use `${variable:=fallback}` to set that variable (in your current t
In Docker-OSX, we assume, `:0.0` is your default `$DISPLAY` variable.
In Docker-OSX, we assume, `:0.0` is your default `$DISPLAY` variable.
You can see what yours is
You can see what yours is
```bash
```bash
echo $DISPLAY
echo $DISPLAY
```
```
Hence, `${DISPLAY:-:0.0}` will use whatever variable your X11 server has set for you, else `:0.0`
## What is `-v /tmp/.X11-unix:/tmp/.X11-unix`?
That way, `${DISPLAY:-:0.0}` will use whatever variable your X11 server has set for you, else `:0.0`
#### What is `-v /tmp/.X11-unix:/tmp/.X11-unix`?
`-v` is a Docker command-line option that lets you pass a volume to the container.
`-v` is a Docker command-line option that lets you pass a volume to the container.
@ -1133,11 +1086,3 @@ The directory that we are letting the Docker container use is a X server display
`/tmp/.X11-unix`
`/tmp/.X11-unix`
If we let the Docker container use the same display socket as our own environment, then any applications you run inside the Docker container will show up on your screen too! [https://www.x.org/archive/X11R6.8.0/doc/RELNOTES5.html](https://www.x.org/archive/X11R6.8.0/doc/RELNOTES5.html)
If we let the Docker container use the same display socket as our own environment, then any applications you run inside the Docker container will show up on your screen too! [https://www.x.org/archive/X11R6.8.0/doc/RELNOTES5.html](https://www.x.org/archive/X11R6.8.0/doc/RELNOTES5.html)
Panagiotis Vasilopoulos
4 years ago