Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure and clean up docs #136

Merged
merged 1 commit into from
Apr 3, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions .web-docs/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@

The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart virtualization](https://github.com/cirruslabs/tart).
The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart](https://tart.run/).

Here are some highlights of Tart:

Expand Down Expand Up @@ -29,19 +29,21 @@ Alternatively, you can use `packer plugins install` to manage installation of th
$ packer plugins install github.com/cirruslabs/tart
```

### Components

#### Builders
#### Installing Tart

- [tart](/packer/integrations/cirruslabs/tart/latest/components/builder/tart) - The builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart virtualization](/~https://github.com/cirruslabs/tart).

### Getting Started

Here is how you can install Tart, pull a remote macOS virtual machine and run it:
The plugin requires a working installation of Tart. To install and verify your installation:

```bash
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-ventura-vanilla:latest ventura-vanilla
tart run ventura-vanilla
```

Or follow the quick start guide [here](https://tart.run/quick-start/).

### Components

#### Builders

- [tart](/packer/integrations/cirruslabs/tart/latest/components/builder/tart) - The builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart](https://tart.run/).

89 changes: 34 additions & 55 deletions .web-docs/components/builder/tart/README.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,49 @@
Type: `tart`

The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart virtualization](https://github.com/cirruslabs/tart).
The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart](https://tart.run/).

Here are some highlights of Tart:
Make sure you have followed the [installation instructions](/packer/integrations/cirruslabs/tart#installation) before continuing.

- Tart uses Apple's own `Virtualization.Framework` for [near-native performance](https://browser.geekbench.com/v5/cpu/compare/14966395?baseline=14966339).
- Push/Pull virtual machines from any OCI-compatible container registry.
- Built-in CI integration.
- Use this Tart Packer Plugin to automate VM creation.
## Example Usage

## How to get started with Tart
Here is a basic example of creating a macOS virtual machine:

Here is how you can install Tart, pull a remote macOS virtual machine and run it:
```hcl
variable "macos_version" {
type = string
default = "ventura"
}

```bash
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-ventura-vanilla:latest ventura-vanilla
tart run ventura-vanilla
source "tart-cli" "tart" {
vm_base_name = "${var.macos_version}-vanilla"
vm_name = "${var.macos_version}-base"
cpu_count = 4
memory_gb = 8
disk_size_gb = 50
ssh_username = "admin"
ssh_password = "admin"
ssh_timeout = "120s"
}

build {
sources = ["source.tart-cli.tart"]

provisioner "shell" {
inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
}

# more provisioners
}
```

Below we'll go through available options of this Packer plugin.
For more advanced examples, please refer to the [`example/` directory](/~https://github.com/cirruslabs/packer-plugin-tart/tree/main/example) and the [macOS](/~https://github.com/cirruslabs/macos-image-templates) and [Linux](/~https://github.com/cirruslabs/linux-image-templates) Packer templates for [Cirrus CI](https://cirrus-ci.org/).

<!-- Builder Configuration Fields -->

### Required Configuration
## Configuration Reference

- `vm_name` (string) - The name of the VM to create (only when `from_ipsw`, `from_iso` or `vm_base_name` are used) and run.

### Optional Configuration
#### Optional:

- `allow_insecure` (boolean) — When cloning the image, connect to the OCI registry via an insecure HTTP protocol.
- `pull_concurrency` (boolean) — Amount of layers to pull concurrently from an OCI registry when pulling the image. Default is 4 for Tart 2.0.0+.
Expand All @@ -50,7 +66,7 @@ Below we'll go through available options of this Packer plugin.
- `ssh_username` (string) - Username to use for the communication over SSH to run provision steps.
- `ssh_password` (string) - Password to use for the communication over SSH to run provision steps.

## HTTP server configuration
### HTTP server configuration

<!-- Code generated from the comments of the HTTPConfig struct in multistep/commonsteps/http_config.go; DO NOT EDIT MANUALLY -->

Expand All @@ -67,7 +83,7 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg
<!-- End of code generated from the comments of the HTTPConfig struct in multistep/commonsteps/http_config.go; -->


### Optional:
#### Optional:

<!-- Code generated from the comments of the HTTPConfig struct in multistep/commonsteps/http_config.go; DO NOT EDIT MANUALLY -->

Expand Down Expand Up @@ -276,8 +292,6 @@ For more examples of various boot commands, see the sample projects from our
<!-- End of code generated from the comments of the BootConfig struct in bootcommand/config.go; -->


For more examples of various boot commands, see [`example/` directory](/~https://github.com/cirruslabs/packer-plugin-tart/tree/main/example) and [macOS Packer Templates for Cirrus CI](/~https://github.com/cirruslabs/macos-image-templates) project on GitHub.

### VNC configuration

<!-- Code generated from the comments of the VNCConfig struct in bootcommand/config.go; DO NOT EDIT MANUALLY -->
Expand All @@ -303,38 +317,3 @@ You can tune this delay on a per-builder basis by specifying
- `boot_key_interval` (duration string | ex: "1h5m2s") - Time in ms to wait between each key press

<!-- End of code generated from the comments of the VNCConfig struct in bootcommand/config.go; -->


### Example Usage

Here is a basic example of creating a macOS virtual machine:

```hcl
variable "macos_version" {
type = string
default = "ventura"
}

source "tart-cli" "tart" {
vm_base_name = "${var.macos_version}-vanilla"
vm_name = "${var.macos_version}-base"
cpu_count = 4
memory_gb = 8
disk_size_gb = 50
ssh_username = "admin"
ssh_password = "admin"
ssh_timeout = "120s"
}

build {
sources = ["source.tart-cli.tart"]

provisioner "shell" {
inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
}

# more provisioners
}
```

For more advanced examples, please referer to [this repository](/~https://github.com/cirruslabs/macos-image-templates).
20 changes: 11 additions & 9 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@

The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart virtualization](https://github.com/cirruslabs/tart).
The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart](https://tart.run/).

Here are some highlights of Tart:

Expand Down Expand Up @@ -29,19 +29,21 @@ Alternatively, you can use `packer plugins install` to manage installation of th
$ packer plugins install github.com/cirruslabs/tart
```

### Components

#### Builders
#### Installing Tart

- [tart](/packer/integrations/cirruslabs/tart/latest/components/builder/tart) - The builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart virtualization](/~https://github.com/cirruslabs/tart).

### Getting Started

Here is how you can install Tart, pull a remote macOS virtual machine and run it:
The plugin requires a working installation of Tart. To install and verify your installation:

```bash
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-ventura-vanilla:latest ventura-vanilla
tart run ventura-vanilla
```

Or follow the quick start guide [here](https://tart.run/quick-start/).

### Components

#### Builders

- [tart](/packer/integrations/cirruslabs/tart/latest/components/builder/tart) - The builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart](https://tart.run/).

90 changes: 35 additions & 55 deletions docs/builders/tart.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: >
The Tart builder is used to create macOS and Linux virtual machines on Apple Silicon hardware.
The Tart builder is used to create macOS and Linux virtual machines for Apple Silicon.
page_title: Tart - Builders
nav_title: Tart
---
Expand All @@ -9,34 +9,50 @@ nav_title: Tart

Type: `tart`

The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart virtualization](https://github.com/cirruslabs/tart).
The `tart` builder is used to create macOS and Linux VMs for Apple Silicon powered by [Tart](https://tart.run/).

Here are some highlights of Tart:
Make sure you have followed the [installation instructions](/packer/integrations/cirruslabs/tart#installation) before continuing.

- Tart uses Apple's own `Virtualization.Framework` for [near-native performance](https://browser.geekbench.com/v5/cpu/compare/14966395?baseline=14966339).
- Push/Pull virtual machines from any OCI-compatible container registry.
- Built-in CI integration.
- Use this Tart Packer Plugin to automate VM creation.
## Example Usage

## How to get started with Tart
Here is a basic example of creating a macOS virtual machine:

Here is how you can install Tart, pull a remote macOS virtual machine and run it:
```hcl
variable "macos_version" {
type = string
default = "ventura"
}

```bash
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-ventura-vanilla:latest ventura-vanilla
tart run ventura-vanilla
source "tart-cli" "tart" {
vm_base_name = "${var.macos_version}-vanilla"
vm_name = "${var.macos_version}-base"
cpu_count = 4
memory_gb = 8
disk_size_gb = 50
ssh_username = "admin"
ssh_password = "admin"
ssh_timeout = "120s"
}

build {
sources = ["source.tart-cli.tart"]

provisioner "shell" {
inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
}

# more provisioners
}
```

Below we'll go through available options of this Packer plugin.
For more advanced examples, please refer to the [`example/` directory](/~https://github.com/cirruslabs/packer-plugin-tart/tree/main/example) and the [macOS](/~https://github.com/cirruslabs/macos-image-templates) and [Linux](/~https://github.com/cirruslabs/linux-image-templates) Packer templates for [Cirrus CI](https://cirrus-ci.org/).

<!-- Builder Configuration Fields -->

### Required Configuration
## Configuration Reference

- `vm_name` (string) - The name of the VM to create (only when `from_ipsw`, `from_iso` or `vm_base_name` are used) and run.

### Optional Configuration
#### Optional:

- `allow_insecure` (boolean) — When cloning the image, connect to the OCI registry via an insecure HTTP protocol.
- `pull_concurrency` (boolean) — Amount of layers to pull concurrently from an OCI registry when pulling the image. Default is 4 for Tart 2.0.0+.
Expand All @@ -59,11 +75,11 @@ Below we'll go through available options of this Packer plugin.
- `ssh_username` (string) - Username to use for the communication over SSH to run provision steps.
- `ssh_password` (string) - Password to use for the communication over SSH to run provision steps.

## HTTP server configuration
### HTTP server configuration

@include 'packer-plugin-sdk/multistep/commonsteps/HTTPConfig.mdx'

### Optional:
#### Optional:

@include 'packer-plugin-sdk/multistep/commonsteps/HTTPConfig-not-required.mdx'

Expand All @@ -75,46 +91,10 @@ Below we'll go through available options of this Packer plugin.

@include 'packer-plugin-sdk/bootcommand/BootConfig-not-required.mdx'

For more examples of various boot commands, see [`example/` directory](/~https://github.com/cirruslabs/packer-plugin-tart/tree/main/example) and [macOS Packer Templates for Cirrus CI](/~https://github.com/cirruslabs/macos-image-templates) project on GitHub.

### VNC configuration

@include 'packer-plugin-sdk/bootcommand/VNCConfig.mdx'

#### Optional:

@include 'packer-plugin-sdk/bootcommand/VNCConfig-not-required.mdx'

### Example Usage

Here is a basic example of creating a macOS virtual machine:

```hcl
variable "macos_version" {
type = string
default = "ventura"
}

source "tart-cli" "tart" {
vm_base_name = "${var.macos_version}-vanilla"
vm_name = "${var.macos_version}-base"
cpu_count = 4
memory_gb = 8
disk_size_gb = 50
ssh_username = "admin"
ssh_password = "admin"
ssh_timeout = "120s"
}

build {
sources = ["source.tart-cli.tart"]

provisioner "shell" {
inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
}

# more provisioners
}
```

For more advanced examples, please referer to [this repository](/~https://github.com/cirruslabs/macos-image-templates).