pal-e-docs

Architecture: Mac Bootstrap

arch-mac-bootstrap Doc

architecture active
Project

Architecture: Mac Bootstrap

Purpose

Define how any Mac (personal MacBook, cloud VM, owned Mac mini) is bootstrapped from bare metal to a functioning iOS build agent. Salt states provide the IaC layer — the same states work regardless of where the Mac lives.

Components

Component Repo Role
Salt states macbook-ssh (future) Xcode CLI tools, certs, keychain, Woodpecker agent install
Orka provider orka-tofu Provision Mac VMs via MacStadium API
Woodpecker agent pal-e-platform Self-hosted CI agent on Mac, connects to Woodpecker server
Keychain + certs macbook-ssh Import signing certs, create ci-build keychain

Bootstrap Sequence

  • tofu apply in orka-tofu provisions a Mac VM (or skip for physical Mac)
  • Salt highstate installs Xcode CLI tools, Homebrew, git
  • Salt imports Apple Developer signing certs into ci-build keychain
  • Salt installs and configures Woodpecker agent (connects to Woodpecker server on pal-e cluster)
  • Mac registers as build agent — Woodpecker pipelines can now target it

Key Constraint

macOS restricts keychain access in non-GUI SSH sessions. Build commands must run through tmux (started from a GUI terminal) or the Woodpecker agent process (which runs as a LaunchAgent). Direct ssh mac "xcodebuild" fails with 0 valid signing identities.
  • Tickets: #1532 (macbook-ssh docs), #1536 (Orka spike)
  • Repos: macbook-ssh, orka-tofu
  • Board: board-project-ios-infrastructure