# sickcodes/docker-osx architecture

> Architecture diagram of the GitHub repository sickcodes/docker-osx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sickcodes/docker-osx
- Repository: https://github.com/sickcodes/docker-osx

## Overview

Docker-OSX packages macOS virtual machines for use in Docker. The main workflow is a user launching a container configured for a macOS release, with the container providing the VM runtime and host-facing access such as display forwarding. The repository also includes a macOS installer fetcher, customization assets, and a Helm deployment chart. The README and excerpts support the fetcher’s catalog/download behavior; runtime wiring and several deployment details are not sampled, so those links are marked unverified rather than asserted.

Main entry points: [`helm/Chart.yaml`](https://github.com/sickcodes/docker-osx/blob/master/helm/Chart.yaml) (Helm chart), [`README.md`](https://github.com/sickcodes/docker-osx/blob/master/README.md) (Docker launch), [`Dockerfile`](https://github.com/sickcodes/docker-osx/blob/master/Dockerfile) (Container images), [`fetch-macOS.py`](https://github.com/sickcodes/docker-osx/blob/master/fetch-macOS.py) (Installer fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Container launch"]
  node_docker["Docker launch<br/>[README.md]"]
  node_images["Container images"]
  node_auto_image["Auto images<br/>[Dockerfile.auto]"]
  node_naked_image["Naked images<br/>[Dockerfile.naked]"]
  node_naked_auto["Naked auto"]
end

subgraph group_vm["Virtual machine"]
  node_vm_runtime["macOS VM runtime"]
  node_host_access["Display and devices<br/>[README.md]"]
end

subgraph group_setup["Installer and customization"]
  node_fetch["Installer fetcher<br/>[fetch-macOS.py]"]
  node_custom_config["Custom boot configs"]
  node_legacy_config["Legacy boot configs"]
  node_bootdisk["Boot disk generator"]
  node_machine_values["Machine values"]
  node_opencore_image["OpenCore image"]
  node_kernel_patch["Kernel patch helper"]
end

subgraph group_deploy["Cluster deployment"]
  node_helm_chart["Helm chart<br/>[Chart.yaml]"]
  node_helm_deployment["VM deployment<br/>[deployment.yaml]"]
  node_helm_storage[("Persistent disk<br/>[data-pvc.yaml]")]
  node_helm_service["Cluster service<br/>[service.yaml]"]
  node_helm_ingress["Ingress route<br/>[ingress.yaml]"]
end

node_user(("Docker user"))
node_apple["Apple software catalogs"]
node_helm_user(("Cluster operator"))

node_user -->|"runs image"| node_docker
node_docker -.->|"selects image"| node_images
node_images -.->|"starts VM"| node_vm_runtime
node_vm_runtime -.->|"offers access"| node_host_access
node_fetch -->|"fetches catalogs"| node_apple
node_helm_user -.->|"deploys chart"| node_helm_chart
node_helm_chart -.->|"renders deployment"| node_helm_deployment
node_helm_chart -.->|"defines storage"| node_helm_storage
node_helm_chart -.->|"defines service"| node_helm_service
node_helm_chart -.->|"defines ingress"| node_helm_ingress

click node_docker "https://github.com/sickcodes/docker-osx/blob/master/README.md"
click node_images "https://github.com/sickcodes/docker-osx/blob/master/Dockerfile"
click node_auto_image "https://github.com/sickcodes/docker-osx/blob/master/Dockerfile.auto"
click node_naked_image "https://github.com/sickcodes/docker-osx/blob/master/Dockerfile.naked"
click node_naked_auto "https://github.com/sickcodes/docker-osx/blob/master/Dockerfile.naked-auto"
click node_vm_runtime "https://github.com/sickcodes/docker-osx/blob/master/Dockerfile"
click node_host_access "https://github.com/sickcodes/docker-osx/blob/master/README.md"
click node_fetch "https://github.com/sickcodes/docker-osx/blob/master/fetch-macOS.py"
click node_custom_config "https://github.com/sickcodes/docker-osx/blob/master/custom/config-custom.plist"
click node_legacy_config "https://github.com/sickcodes/docker-osx/blob/master/custom/config-legacy.plist"
click node_bootdisk "https://github.com/sickcodes/docker-osx/blob/master/custom/generate-specific-bootdisk.sh"
click node_machine_values "https://github.com/sickcodes/docker-osx/blob/master/custom/generate-unique-machine-values.sh"
click node_opencore_image "https://github.com/sickcodes/docker-osx/blob/master/custom/opencore-image-ng.sh"
click node_kernel_patch "https://github.com/sickcodes/docker-osx/blob/master/scripts/apply_appleid_kernelpatch.py"
click node_helm_chart "https://github.com/sickcodes/docker-osx/blob/master/helm/Chart.yaml"
click node_helm_deployment "https://github.com/sickcodes/docker-osx/blob/master/helm/templates/deployment.yaml"
click node_helm_storage "https://github.com/sickcodes/docker-osx/blob/master/helm/templates/data-pvc.yaml"
click node_helm_service "https://github.com/sickcodes/docker-osx/blob/master/helm/templates/service.yaml"
click node_helm_ingress "https://github.com/sickcodes/docker-osx/blob/master/helm/templates/ingress.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_docker,node_images,node_auto_image,node_naked_image,node_naked_auto,node_user toneBlue
class node_vm_runtime,node_host_access toneAmber
class node_fetch,node_custom_config,node_legacy_config,node_bootdisk,node_machine_values,node_opencore_image,node_kernel_patch toneMint
class node_helm_chart,node_helm_deployment,node_helm_storage,node_helm_service,node_helm_ingress toneRose
class node_apple,node_helm_user toneIndigo
```

## Components

### Container launch

- [Docker launch](https://github.com/sickcodes/docker-osx/blob/master/README.md): `README.md`
- [Container images](https://github.com/sickcodes/docker-osx/blob/master/Dockerfile): `Dockerfile`
- [Auto images](https://github.com/sickcodes/docker-osx/blob/master/Dockerfile.auto): `Dockerfile.auto`
- [Naked images](https://github.com/sickcodes/docker-osx/blob/master/Dockerfile.naked): `Dockerfile.naked`
- [Naked auto](https://github.com/sickcodes/docker-osx/blob/master/Dockerfile.naked-auto): `Dockerfile.naked-auto`

### Virtual machine

- [macOS VM runtime](https://github.com/sickcodes/docker-osx/blob/master/Dockerfile): `Dockerfile`
- [Display and devices](https://github.com/sickcodes/docker-osx/blob/master/README.md): `README.md`

### Installer and customization

- [Installer fetcher](https://github.com/sickcodes/docker-osx/blob/master/fetch-macOS.py): `fetch-macOS.py`
- [Custom boot configs](https://github.com/sickcodes/docker-osx/blob/master/custom/config-custom.plist): `custom/config-custom.plist`
- [Legacy boot configs](https://github.com/sickcodes/docker-osx/blob/master/custom/config-legacy.plist): `custom/config-legacy.plist`
- [Boot disk generator](https://github.com/sickcodes/docker-osx/blob/master/custom/generate-specific-bootdisk.sh): `custom/generate-specific-bootdisk.sh`
- [Machine values](https://github.com/sickcodes/docker-osx/blob/master/custom/generate-unique-machine-values.sh): `custom/generate-unique-machine-values.sh`
- [OpenCore image](https://github.com/sickcodes/docker-osx/blob/master/custom/opencore-image-ng.sh): `custom/opencore-image-ng.sh`
- [Kernel patch helper](https://github.com/sickcodes/docker-osx/blob/master/scripts/apply_appleid_kernelpatch.py): `scripts/apply_appleid_kernelpatch.py`

### Cluster deployment

- [Helm chart](https://github.com/sickcodes/docker-osx/blob/master/helm/Chart.yaml): `helm/Chart.yaml`
- [VM deployment](https://github.com/sickcodes/docker-osx/blob/master/helm/templates/deployment.yaml): `helm/templates/deployment.yaml`
- [Persistent disk](https://github.com/sickcodes/docker-osx/blob/master/helm/templates/data-pvc.yaml): `helm/templates/data-pvc.yaml`
- [Cluster service](https://github.com/sickcodes/docker-osx/blob/master/helm/templates/service.yaml): `helm/templates/service.yaml`
- [Ingress route](https://github.com/sickcodes/docker-osx/blob/master/helm/templates/ingress.yaml): `helm/templates/ingress.yaml`

### Other components

- **Docker user**
- **Apple software catalogs**
- **Cluster operator**

## Connections

- Docker user → Docker launch: runs image (evidence: `README.md`)
- Docker launch → Container images: selects image
- Container images → macOS VM runtime: starts VM
- macOS VM runtime → Display and devices: offers access
- Installer fetcher → Apple software catalogs: fetches catalogs (evidence: `fetch-macOS.py`)
- Cluster operator → Helm chart: deploys chart
- Helm chart → VM deployment: renders deployment
- Helm chart → Persistent disk: defines storage
- Helm chart → Cluster service: defines service
- Helm chart → Ingress route: defines ingress
