From f712ba8ce36e072df7554253698695977fdaf8e7 Mon Sep 17 00:00:00 2001 From: Fedor Korotkov Date: Fri, 6 May 2022 16:59:33 -0400 Subject: [PATCH] Proper documentation (#49) * WIP proper docs * Update README.md * wip * More updates * Apply suggestions from code review Co-authored-by: Nikolay Edigaryev * Use GitHub Packages links * Promote Cirrus CLI first and then mentioned Cirrus CI * Apply suggestions from code review Co-authored-by: Nikolay Edigaryev Co-authored-by: Nikolay Edigaryev --- README.md | 155 ++++++++++++++++++++++++++++++++++- Resources/TartScreenshot.png | 3 + 2 files changed, 156 insertions(+), 2 deletions(-) create mode 100644 Resources/TartScreenshot.png diff --git a/README.md b/README.md index cc994722..e477ce0e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,154 @@ -# Tart +![tart VM view app](Resources/TartScreenshot.png) -macOS VMs on Apple Silicon to use in CI and other automations +*Tart* is a virtualization toolset to build, run and manage virtual machines on Apple Silicon. +Built by CI engineers for your automation needs. Here are some highlights of Tart: + +* Tart uses Apple's own `Virtualization.Framework` for near-native performance. +* Push/Pull virtual machines from any OCI-compatible container registry. +* Use Tart Packer Plugin to automate VM creation. +* Built-in CI integration. + +Try running a Tart VM on your Apple Silicon device (will download a 25 GB image): + +```shell +brew install cirruslabs/cli/tart +tart clone ghcr.io/cirruslabs/macos-monterey-base:latest monterey-base +tart run monterey-base +``` + +## CI Integration + +[Cirrus CLI](https://github.com/cirruslabs/cirrus-cli) is an open-sourced CI-agnostic tool that can run workloads +inside containers via Docker or Podman and now inside macOS VMs via Tart. Put the following `.cirrus.yml` file +in the root of your repository: + +```yaml +task: + name: hello + macos_instance: + # can be a remote or a local virtual machine + image: ghcr.io/cirruslabs/macos-monterey-base:latest + script: echo "Hello from within a Tart VM!" +``` + +Run it locally or in CI with the following command: + +```shell +brew install cirruslabs/cli/cirrus +cirrus run +``` + +[Cirrus CI](https://cirrus-ci.org/) already leverages Tart to power its macOS cloud infrastructure. The `.cirrus.yml` +config from above will just work in Cirrus CI and your tasks will be executed inside Tart VMs in our cloud. + +**Note:** Cirrus CI only allows [images managed and regularly updated by us](https://github.com/orgs/cirruslabs/packages?tab=packages&q=macos). + +## Virtual Machine Management + +### Creating from scratch + +Tart can create VMs from `*.ipsw` files. You can download a specific `*.ipsw` file [here](https://ipsw.me/) or you can +use `latest` instead of a path to `*.ipsw` to download the latest available version: + +```shell +tart create --from-ipsw=latest monterey-vanilla +tart run monterey-vanilla +``` + +After the initial booting of the VM you'll need to manually go through the macOS installation process. As a convention we recommend creating an `admin` user with an `admin` password. After the regular installation please do some additional modifications in the VM: + +1. Enable Auto-Login. Users & Groups -> Login Options -> Automatic login -> admin. +2. Allow SSH. Sharing -> Remote Login +3. Disable Lock Screen. Preferences -> Lock Screen -> disable "Require Password" after 5. +4. Disable Screen Saver. +5. Run `sudo visudo` in Terminal, find `%admin ALL=(ALL) ALL` add `admin ALL=(ALL) NOPASSWD: ALL` to allow sudo without a password. + +### Configuring a VM + +By default, a tart VM uses 2 CPUs and 4 GB of memory with a `1024x768` display. This can be changed with `tart set` command. +Please refer to `tart set --help` for additional details. + +### Building with Packer + +Please refer to [Tart Packer Plugin reposiotry](https://github.com/cirruslabs/packer-plugin-tart) for setup instructions. +Here is an example of a template to build `monterey-base` local image based of a remote image: + +```json +{ + "builders": [ + { + "name": "tart", + "type": "tart-cli", + "vm_base_name": "tartvm/vanilla:latest", + "vm_name": "monterey-base", + "cpu_count": 4, + "memory_gb": 8, + "disk_size_gb": 32, + "ssh_username": "admin", + "ssh_password": "admin", + "ssh_timeout": "120s" + } + ], + "provisioners": [ + { + "inline": [ + "echo 'Disabling spotlight indexing...'", + "sudo mdutil -a -i off" + ], + "type": "shell" + }, + # more provisioners + ] +} +``` + +Here is a [repository with Packer templates](https://github.com/cirruslabs/macos-image-templates) used to build [all the images managed by us](https://github.com/orgs/cirruslabs/packages?tab=packages&q=macos). + +### Working with a Remote OCI Container Registry + +For example, let's say you want to push/pull images to a registry hosted at https://acme.io/. + +#### Registry Authorization + +First, you need to log in and save credential for `acme.io` host via `tart login` command: + +```shell +tart login acme.io +``` + +Credentials are securely stored in Keychain. + +#### Pushing a Local Image + +Once credentials are saved for `acme.io`, run the following command to push a local images remotely with two tags: + +```shell +tart push my-local-vm-name acme.io/remoteorg/name:latest acme.io/remoteorg/name:v1.0.0 +``` + +#### Pulling a Remote Image + +```shell +tart pull acme.io/remoteorg/name:latest my-local-vm-name +``` + +## FAQ + +
+ How Tart is different from Anka + + Under the hood Tart is using the same technology as Anka 3.0 so there should be no real difference in performance + or features supported. If there is some feature missing please don't hesitate to [create a feature request](https://github.com/cirruslabs/tart/issues). + + Instead of Anka Registry, Tart can work with any OCI-compatible container registry. + + Tart doesn't yet have an analogue of Anka Controller for managing long living VMs. Please take a look at [CI integration](#ci-integration) + section for an option to run ephemeral VMs for your needs. +
+ +
+ Why Tart is free and open sourced? + + Tart is a relatively small project, and it didn't feel right to try to monetize it. + Apple did all the heavy lifting with their `Virtualization.Framework`. +
diff --git a/Resources/TartScreenshot.png b/Resources/TartScreenshot.png new file mode 100644 index 00000000..e7c4d56b --- /dev/null +++ b/Resources/TartScreenshot.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:46046004d63f9b4b7de3d5d3f9ca14367a9e4b0a124b4b0b65225f67a0d0fb45 +size 1266887