# dockur/macos architecture

> Architecture diagram of the GitHub repository dockur/macos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dockur/macos
- Repository: https://github.com/dockur/macos

## Overview

##### Major Components
- Docker Container Environment: The central unit is the Docker container which runs macOS. It is built using the provided Dockerfile and uses scripts from the src/ folder (boot.sh, entry.sh, install.sh) for initialization.
- Virtualization Backend: Underneath, QEMU is used with KVM acceleration (as indicated by the README and the need for /dev/kvm). This virtualization layer provides the performance boost.
- Web-based Viewer: The container exposes a web interface (port 8006) that allows interactions such as disk formatting and installation. Also, VNC ports (5900 TCP/UDP) are available.
- Data Persistence: There is a volume mount (typically mapped to a host directory such as ./macos:/storage) to store virtual disk images or macOS installation data persistently.
- Networking Configuration: Various networking modes are supported:
– Default bridge networking with explicit port mapping.
– macvlan network configuration that assigns an individual IP address (with its own considerations regarding host accessibility).
- Deployment Mechanisms: There are multiple configuration files provided (compose.yml, kubernetes.yml) to assist with different deployment platforms.
- Build & CI/CD Pipelines: The .github directory contains workflows for building, testing, and validating the container. This reflects a continuous integration setup.
- Assets & Configurations: The assets/config.plist file is likely used to configure macOS-specific parameters inside the container.

##### Relationships and Interactions
- The Docker container (macos) acts as an encapsulated environment where macOS is run using QEMU/KVM. It requires direct access to hardware devices (e.g., /dev/kvm, /dev/net/tun, and USB devices if needed) which are passed from the host.
- The container initialization process is managed by the scripts in the src/ directory. These scripts (boot.sh, entry.sh, install.sh) likely set up the QEMU environment and start macOS.
- Interaction with users happens mainly through the web-based viewer which is accessed via the mapped port 8006. Additionally, VNC access on port 5900 is available.
- Persistent data (such as disk images) is stored on the host’s file system via volume binding (e.g., ./macos:/storage). This ensures data persists beyond container restarts.

##### Important Architectural Patterns and Design Principles
- Containerization: The system leverages Docker to encapsulate the macOS environment, ensuring portability and isolation.
- Virtualization Acceleration: The design integrates hardware-level acceleration (KVM) to optimize performance when running a full OS inside a container.
- Modularity: The project separates concerns clearly with independent configuration files (Dockerfile, compose.yml, kubernetes.yml) and initialization scripts (in src/). This keeps deployment and runtime configurations distinct.
- Extensibility: With options to configure CPU, memory, disk size, network settings, and USB pass-through, the architecture is designed to be flexible and customizable based on user needs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Layer"
        HOST["Host System\n(Devices: /dev/kvm, /dev/net/tun)"]:::host
        STORAGE["Persistent Storage (/macos)"]:::storage
    end

    subgraph "Orchestration Layer"
        DOCKER_ENGINE["Docker Engine"]:::docker
        CICD["CI/CD Pipeline"]:::cicd
    end

    subgraph "Deployment Files"
        DOCKERFILE["Dockerfile"]:::config
        COMPOSE["docker-compose.yml"]:::config
        KUBERNETES["kubernetes.yml"]:::config
    end

    subgraph "Container Layer"
        CONTAINER["macOS Container (QEMU/KVM)"]:::container
        subgraph "Initialization Scripts"
            BOOT["boot.sh"]:::init
            ENTRY["entry.sh"]:::init
            INSTALL["install.sh"]:::init
        end
        ASSETS["Assets Configuration"]:::assets
        WEB["Web Viewer & VNC\n(Ports 8006,5900)"]:::web
    end

    %% Relationships
    HOST -->|"Pass-devices"| CONTAINER
    STORAGE -->|"Volume-mount"| CONTAINER

    DOCKERFILE --> DOCKER_ENGINE
    COMPOSE --> DOCKER_ENGINE
    KUBERNETES --> DOCKER_ENGINE

    CICD --> DOCKERFILE
    CICD --> COMPOSE
    CICD --> KUBERNETES

    DOCKER_ENGINE --> CONTAINER

    BOOT --> CONTAINER
    ENTRY --> CONTAINER
    INSTALL --> CONTAINER

    ASSETS --> CONTAINER
    WEB --> CONTAINER

    %% Click Events
    click DOCKERFILE "https://github.com/dockur/macos/tree/master/Dockerfile"
    click COMPOSE "https://github.com/dockur/macos/blob/master/compose.yml"
    click KUBERNETES "https://github.com/dockur/macos/blob/master/kubernetes.yml"
    click BOOT "https://github.com/dockur/macos/blob/master/src/boot.sh"
    click ENTRY "https://github.com/dockur/macos/blob/master/src/entry.sh"
    click INSTALL "https://github.com/dockur/macos/blob/master/src/install.sh"
    click CICD "https://github.com/dockur/macos/tree/master/.github/workflows"
    click ASSETS "https://github.com/dockur/macos/blob/master/assets/config.plist"

    %% Styles
    classDef host fill:#ffcccc,stroke:#aa0000,stroke-width:2px;
    classDef storage fill:#fff0f5,stroke:#d147a3,stroke-width:2px;
    classDef docker fill:#ccffcc,stroke:#008800,stroke-width:2px;
    classDef container fill:#ccccff,stroke:#3333ff,stroke-width:2px;
    classDef config fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef init fill:#ccffff,stroke:#00cccc,stroke-width:2px;
    classDef cicd fill:#e0e0e0,stroke:#888888,stroke-width:2px;
    classDef assets fill:#ffe6ff,stroke:#cc0099,stroke-width:2px;
    classDef web fill:#e6ffe6,stroke:#00aa00,stroke-width:2px;
```
