mirror of https://github.com/cirruslabs/tart.git
Documentation Website (#380)
* Move to mkdocs for docs * Deploy task * Custom landing page * Setup Google Analytics * Cropped animation * Update docs/theme/overrides/home.html Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Direct to website and discussions Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com>
This commit is contained in:
Fedor Korotkov
GitHub
parent
ba4f00fa78
commit
bd87e1a8b1
13
.cirrus.yml
13
.cirrus.yml
|
|
@ -94,3 +94,16 @@ task:
|
|||
- sentry-cli releases new $SENTRY_RELEASE
|
||||
- sentry-cli releases set-commits $SENTRY_RELEASE --auto
|
||||
- sentry-cli releases finalize $SENTRY_RELEASE
|
||||
|
||||
task:
|
||||
name: Deploy Documentation
|
||||
only_if: $CIRRUS_BRANCH == 'main'
|
||||
container:
|
||||
image: ghcr.io/squidfunk/mkdocs-material:latest
|
||||
env:
|
||||
DEPLOY_TOKEN: ENCRYPTED[!45ed45666558902ed1c2400add734ec063103bec31841847e8c8764802fca229bfa6d85c690e16ad159e047574b48793!]
|
||||
deploy_script:
|
||||
- git config --global user.name "Cirrus CI"
|
||||
- git config --global user.name "hello@cirruslabs.org"
|
||||
- git remote set-url origin https://$DEPLOY_TOKEN@github.com/cirruslabs/tart/
|
||||
- mkdocs --verbose gh-deploy --force --remote-branch gh-pages
|
||||
|
|
|
|||
|
|
@ -1,2 +1,5 @@
|
|||
*.png filter=lfs diff=lfs merge=lfs -text
|
||||
*.gif filter=lfs diff=lfs merge=lfs -text
|
||||
*.ico filter=lfs diff=lfs merge=lfs -text
|
||||
*.webp filter=lfs diff=lfs merge=lfs -text
|
||||
*.lottie filter=lfs diff=lfs merge=lfs -text
|
||||
|
|
|
|||
283
README.md
283
README.md
|
|
@ -48,277 +48,8 @@ tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base
|
|||
tart run ventura-base
|
||||
```
|
||||
|
||||
<img src="https://github.com/cirruslabs/tart/raw/main/Resources/TartScreenshot.png"/>
|
||||
|
||||
## CI Integration
|
||||
|
||||
Tart already powers several CI services mentioned above including our own [Cirrus CI](https://cirrus-ci.org/guide/macOS/) which offers unlimited concurrency with per-second billing.
|
||||
For services that haven't leveraged Tart yet, we offer fully managed runners via a monthly subscription.
|
||||
*Cirrus Runners* is the fastest way to get your current CI workflows to benefit from Apple Silicon hardware. No need to manage infrastructure or migrate to another CI provider.
|
||||
Please read down below about currently supported services.
|
||||
|
||||
### Managed runners for your CI-as-a-service
|
||||
|
||||
At the moment Cirrus Runners only supports GitHub Actions, but we are actively working on adding more options.
|
||||
Please [email us](mailto:hello@cirruslabs.org) if you are interested in a particular one.
|
||||
|
||||
#### GitHub Actions
|
||||
|
||||
Configuring Cirrus Runners for GitHub Actions is as simple as installing [Cirrus Runners App](https://github.com/apps/cirrus-runners).
|
||||
After successful installation and subscription configuration, use any of [Ventura images managed by us](https://github.com/cirruslabs/macos-image-templates) in `runs-on`:
|
||||
|
||||
```yaml
|
||||
name: Test Suite
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ghcr.io/cirruslabs/macos-ventura-xcode:latest
|
||||
```
|
||||
|
||||
When workflows are executing you'll see Cirrus on-demand runners on your organization's settings page at `https://github.com/organizations/<ORGANIZATION>/settings/actions/runners`.
|
||||
|
||||
<img src="https://github.com/cirruslabs/tart/raw/main/Resources/TartGHARunners.png"/>
|
||||
|
||||
### Self-hosted CI
|
||||
|
||||
Tart itself is only responsible for managing virtual machines, but we've built Tart support into a tool called Cirrus CLI
|
||||
also developed by Cirrus Labs. [Cirrus CLI](https://github.com/cirruslabs/cirrus-cli) is a command line tool with
|
||||
one configuration format to execute common CI steps (run a script, cache a folder, etc.) locally or in any CI system.
|
||||
We built Cirrus CLI to solve "But it works on my machine!" problem.
|
||||
|
||||
Here is an example of a `.cirrus.yml` configuration file which will start a Tart VM, will copy over working directory and
|
||||
will run scripts and [other instructions](https://cirrus-ci.org/guide/writing-tasks/#supported-instructions) inside the virtual machine:
|
||||
|
||||
```yaml
|
||||
task:
|
||||
name: hello
|
||||
macos_instance:
|
||||
# can be a remote or a local virtual machine
|
||||
image: ghcr.io/cirruslabs/macos-monterey-base:latest
|
||||
hello_script:
|
||||
- echo "Hello from within a Tart VM!"
|
||||
- echo "Here is my CPU info:"
|
||||
- sysctl -n machdep.cpu.brand_string
|
||||
- sleep 15
|
||||
```
|
||||
|
||||
Put the above `.cirrus.yml` file in the root of your repository and run it with the following command:
|
||||
|
||||
```shell
|
||||
brew install cirruslabs/cli/cirrus
|
||||
cirrus run
|
||||
```
|
||||
|
||||
<img src="https://github.com/cirruslabs/tart/raw/main/Resources/TartCirrusCLI.gif"/>
|
||||
|
||||
[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).
|
||||
|
||||
#### Retrieving artifacts from within Tart VMs
|
||||
|
||||
In many cases there is a need to retrieve particular files or a folder from within a Tart virtual machine.
|
||||
For example, the below `.cirrus.yml` configuration defines a single task that builds a `tart` binary and
|
||||
exposes it via [`artifacts` instruction](https://cirrus-ci.org/guide/writing-tasks/#artifacts-instruction):
|
||||
|
||||
```yaml
|
||||
task:
|
||||
name: Build
|
||||
macos_instance:
|
||||
image: ghcr.io/cirruslabs/macos-monterey-xcode:latest
|
||||
build_script: swift build --product tart
|
||||
binary_artifacts:
|
||||
path: .build/debug/tart
|
||||
```
|
||||
|
||||
Running Cirrus CLI with `--artifacts-dir` will write defined `artifacts` to the provided local directory on the host:
|
||||
|
||||
```shell
|
||||
cirrus run --artifacts-dir artifacts
|
||||
```
|
||||
|
||||
Note that all retrieved artifacts will be prefixed with the associated task name and `artifacts` instruction name.
|
||||
For the example above, `tart` binary will be saved to `$PWD/artifacts/Build/binary/.build/debug/tart`.
|
||||
|
||||
## Virtual Machine Management
|
||||
|
||||
### Creating from scratch
|
||||
|
||||
Tart supports macOS and Linux virtual machines. All commands like `run` and `pull` work the same way regarding of the underlying OS a particular VM image has.
|
||||
The only difference is how such VM images are created. Please check sections below for [macOS](#creating-a-macos-vm-image-from-scratch) and [Linux](#creating-a-linux-vm-image-from-scratch) instructions.
|
||||
|
||||
#### Creating a macOS VM image 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.
|
||||
|
||||
#### Creating a Linux VM image from scratch
|
||||
|
||||
Linux VMs are supported on hosts running macOS 13.0 (Ventura) or newer.
|
||||
|
||||
```shell
|
||||
# Create a bare VM
|
||||
tart create --linux ubuntu
|
||||
|
||||
# Install Ubuntu
|
||||
tart run --disk focal-desktop-arm64.iso ubuntu
|
||||
|
||||
# Run VM
|
||||
tart run ubuntu
|
||||
```
|
||||
|
||||
After the initial setup please make sure your VM can be SSH-ed into by running the following commands inside your VM:
|
||||
|
||||
```shell
|
||||
sudo apt update
|
||||
sudo apt install -y openssh-server
|
||||
sudo ufw allow ssh
|
||||
```
|
||||
|
||||
### 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 repository](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:
|
||||
|
||||
```hcl
|
||||
packer {
|
||||
required_plugins {
|
||||
tart = {
|
||||
version = ">= 0.5.3"
|
||||
source = "github.com/cirruslabs/tart"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
source "tart-cli" "tart" {
|
||||
vm_base_name = "ghcr.io/cirruslabs/macos-ventura-base:latest"
|
||||
vm_name = "my-custom-ventura"
|
||||
cpu_count = 4
|
||||
memory_gb = 8
|
||||
disk_size_gb = 70
|
||||
ssh_password = "admin"
|
||||
ssh_timeout = "120s"
|
||||
ssh_username = "admin"
|
||||
}
|
||||
|
||||
build {
|
||||
sources = ["source.tart-cli.tart"]
|
||||
|
||||
provisioner "shell" {
|
||||
inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
|
||||
}
|
||||
|
||||
# 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.
|
||||
|
||||
In addition, Tart supports [Docker credential helpers](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers)
|
||||
if defined in `~/.docker/config.json`.
|
||||
|
||||
Finally, `TART_REGISTRY_USERNAME` and `TART_REGISTRY_PASSWORD` environment variables allow to override authorization
|
||||
for all registries which might useful for integrating with your CI's secret management.
|
||||
|
||||
#### 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
|
||||
|
||||
You can either pull an image:
|
||||
|
||||
```shell
|
||||
tart pull acme.io/remoteorg/name:latest
|
||||
```
|
||||
|
||||
...or instantiate a VM from a remote image:
|
||||
|
||||
```shell
|
||||
tart clone acme.io/remoteorg/name:latest my-local-vm-name
|
||||
```
|
||||
|
||||
This invocation calls the `tart pull` implicitly (if the image is not being present) before doing the actual cloning.
|
||||
|
||||
### Mounting directories
|
||||
|
||||
To mount a directory, run the VM with the `--dir` argument:
|
||||
|
||||
```shell
|
||||
tart run --dir=project:~/src/project vm
|
||||
```
|
||||
|
||||
Here, the `project` specifies a mount name, whereas the `~/src/project` is a path to the host's directory to expose to the VM.
|
||||
|
||||
It is also possible to mount directories in read-only mode by adding a third parameter, `ro`:
|
||||
|
||||
```shell
|
||||
tart run --dir=project:~/src/project:ro vm
|
||||
```
|
||||
|
||||
To mount multiple directories, repeat the `--dir` argument for each directory:
|
||||
|
||||
```shell
|
||||
tart run --dir=www1:~/project1/www --dir=www2:~/project2/www
|
||||
```
|
||||
|
||||
Note that the first parameter in each `--dir` argument must be unique, otherwise only the last `--dir` argument using that name will be used.
|
||||
|
||||
Note: to use the directory mounting feature, the host needs to run macOS 13.0 (Ventura) or newer.
|
||||
|
||||
#### Accessing mounted directories in macOS guests
|
||||
|
||||
All shared directories are automatically mounted to `/Volumes/My Shared Files` directory.
|
||||
|
||||
The directory we've mounted above will be accessible from the `/Volumes/My Shared Files/project` path inside a guest VM.
|
||||
|
||||
Note: to use the directory mounting feature, the guest VM needs to run macOS 13.0 (Ventura) or newer.
|
||||
|
||||
#### Accessing mounted directories in Linux guests
|
||||
|
||||
To be able to access the shared directories from the Linux guest, you need to manually mount the virtual filesystem first:
|
||||
|
||||
```shell
|
||||
mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared
|
||||
```
|
||||
|
||||
The directory we've mounted above will be accessible from the `/mnt/shared/project` path inside a guest VM.
|
||||
Please check the [official documentation](https://tart.run) for more information and/or feel free to use [discussions](https://github.com/cirruslabs/tart/discussions)
|
||||
for remaining questions.
|
||||
|
||||
## FAQ
|
||||
|
||||
|
|
@ -385,13 +116,3 @@ The directory we've mounted above will be accessible from the `/mnt/shared/proje
|
|||
sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.vmnet.plist Shared_Net_Mask -string 255.255.0.0
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>How to connect to a VM over SSH?</summary>
|
||||
|
||||
If the guest VM is running and configured to accept incoming SSH connections you can conveniently connect to it like so:
|
||||
|
||||
```shell
|
||||
ssh admin@$(tart ip macos-monterey-base)
|
||||
```
|
||||
</details>
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:769dcd5411f44071cb46f63459118fef728c866a581cf94a28811f407ca9827d
|
||||
size 606936
|
||||
oid sha256:18ff880508365cea59c5538ab8f1593093436c3f0eec42ca0504f806e7b5dcc0
|
||||
size 582270
|
||||
|
|
|
|||
|
|
@ -0,0 +1,2 @@
|
|||
tart.run
|
||||
www.tart.run
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:1d9cef166b57d57e29b1821fbc06ea2ea5ac92cf29d526ce17c88b9942d2d89d
|
||||
size 7392
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<svg width="146px" height="165px" viewBox="0 0 146 165" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>cirrus-logo</title>
|
||||
<defs></defs>
|
||||
<g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" stroke-linecap="round">
|
||||
<g id="cirrus-logo" transform="translate(7.000000, 7.000000)" stroke="#333333" stroke-width="13.5">
|
||||
<path d="M0,126.494118 L111,126.494118" id="Shape" fill="#000000" fill-rule="nonzero"></path>
|
||||
<path d="M111,126.494118 C122.59798,126.494118 132,117.055227 132,105.411765 C132,93.7683027 122.59798,84.3294118 111,84.3294118" id="Shape"></path>
|
||||
<path d="M0,84.3294118 L111,84.3294118" id="Shape" fill="#000000" fill-rule="nonzero"></path>
|
||||
<path d="M111,84.3294118 C122.59798,84.3294118 132,74.8905208 132,63.2470588 C132,51.6035968 122.59798,42.1647059 111,42.1647059" id="Shape"></path>
|
||||
<path d="M0,42.1647059 L111,42.1647059" id="Shape" fill="#000000" fill-rule="nonzero"></path>
|
||||
<path d="M111,42.1647059 C122.59798,42.1647057 132,32.7258148 132,21.0823529 C132,9.43889104 122.59798,1.73501101e-07 111,-3.55271368e-15" id="Shape"></path>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 99 KiB |
|
|
@ -0,0 +1,3 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:6e3985ec2459dfe94f3a761cbe4bb6895096650950ab0bf7f8ab4b6338c0a915
|
||||
size 15406
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
hide:
|
||||
- navigation
|
||||
---
|
||||
|
||||
# Cirrus CLI
|
||||
|
||||
Tart itself is only responsible for managing virtual machines, but we've built Tart support into a tool called Cirrus CLI
|
||||
also developed by Cirrus Labs. [Cirrus CLI](https://github.com/cirruslabs/cirrus-cli) is a command line tool with
|
||||
one configuration format to execute common CI steps (run a script, cache a folder, etc.) locally or in any CI system.
|
||||
We built Cirrus CLI to solve "But it works on my machine!" problem.
|
||||
|
||||
Here is an example of a `.cirrus.yml` configuration file which will start a Tart VM, will copy over working directory and
|
||||
will run scripts and [other instructions](https://cirrus-ci.org/guide/writing-tasks/#supported-instructions) inside the virtual machine:
|
||||
|
||||
```yaml
|
||||
task:
|
||||
name: hello
|
||||
macos_instance:
|
||||
# can be a remote or a local virtual machine
|
||||
image: ghcr.io/cirruslabs/macos-monterey-base:latest
|
||||
hello_script:
|
||||
- echo "Hello from within a Tart VM!"
|
||||
- echo "Here is my CPU info:"
|
||||
- sysctl -n machdep.cpu.brand_string
|
||||
- sleep 15
|
||||
```
|
||||
|
||||
Put the above `.cirrus.yml` file in the root of your repository and run it 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).
|
||||
|
||||
## Retrieving artifacts from within Tart VMs
|
||||
|
||||
In many cases there is a need to retrieve particular files or a folder from within a Tart virtual machine.
|
||||
For example, the below `.cirrus.yml` configuration defines a single task that builds a `tart` binary and
|
||||
exposes it via [`artifacts` instruction](https://cirrus-ci.org/guide/writing-tasks/#artifacts-instruction):
|
||||
|
||||
```yaml
|
||||
task:
|
||||
name: Build
|
||||
macos_instance:
|
||||
image: ghcr.io/cirruslabs/macos-monterey-xcode:latest
|
||||
build_script: swift build --product tart
|
||||
binary_artifacts:
|
||||
path: .build/debug/tart
|
||||
```
|
||||
|
||||
Running Cirrus CLI with `--artifacts-dir` will write defined `artifacts` to the provided local directory on the host:
|
||||
|
||||
```shell
|
||||
cirrus run --artifacts-dir artifacts
|
||||
```
|
||||
|
||||
Note that all retrieved artifacts will be prefixed with the associated task name and `artifacts` instruction name.
|
||||
For the example above, `tart` binary will be saved to `$PWD/artifacts/Build/binary/.build/debug/tart`.
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
hide:
|
||||
- navigation
|
||||
---
|
||||
|
||||
# GitHub Actions
|
||||
|
||||
Tart already powers several CI services mentioned above including our own [Cirrus CI](https://cirrus-ci.org/guide/macOS/) which offers unlimited concurrency with per-second billing.
|
||||
For services that haven't leveraged Tart yet, we offer fully managed runners via a monthly subscription.
|
||||
*Cirrus Runners* is the fastest way to get your current CI workflows to benefit from Apple Silicon hardware. No need to manage infrastructure or migrate to another CI provider.
|
||||
|
||||
## Configuring Cirrus Runners
|
||||
|
||||
Configuring Cirrus Runners for GitHub Actions is as simple as installing [Cirrus Runners App](https://github.com/apps/cirrus-runners).
|
||||
After successful installation and subscription configuration, use any of [Ventura images managed by us](https://github.com/cirruslabs/macos-image-templates) in `runs-on`:
|
||||
|
||||
```yaml
|
||||
name: Test Suite
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ghcr.io/cirruslabs/macos-ventura-xcode:latest
|
||||
```
|
||||
|
||||
When workflows are executing you'll see Cirrus on-demand runners on your organization's settings page at `https://github.com/organizations/<ORGANIZATION>/settings/actions/runners`.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
template: overrides/home.html
|
||||
title: Tart
|
||||
---
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
hide:
|
||||
- navigation
|
||||
---
|
||||
|
||||
Try running a Tart VM on your Apple Silicon device running macOS 12.0 (Monterey) or later (will download a 25 GB image):
|
||||
|
||||
```shell
|
||||
brew install cirruslabs/cli/tart
|
||||
tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base
|
||||
tart run ventura-base
|
||||
```
|
||||
|
||||
<p align="center">
|
||||
<img src="https://github.com/cirruslabs/tart/raw/main/Resources/TartScreenshot.png"/>
|
||||
</p>
|
||||
|
||||
## SSH access
|
||||
|
||||
If the guest VM is running and configured to accept incoming SSH connections you can conveniently connect to it like so:
|
||||
|
||||
```shell
|
||||
ssh admin@$(tart ip macos-monterey-base)
|
||||
```
|
||||
|
||||
## Mounting directories
|
||||
|
||||
To mount a directory, run the VM with the `--dir` argument:
|
||||
|
||||
```shell
|
||||
tart run --dir=project:~/src/project vm
|
||||
```
|
||||
|
||||
Here, the `project` specifies a mount name, whereas the `~/src/project` is a path to the host's directory to expose to the VM.
|
||||
|
||||
It is also possible to mount directories in read-only mode by adding a third parameter, `ro`:
|
||||
|
||||
```shell
|
||||
tart run --dir=project:~/src/project:ro vm
|
||||
```
|
||||
|
||||
To mount multiple directories, repeat the `--dir` argument for each directory:
|
||||
|
||||
```shell
|
||||
tart run --dir=www1:~/project1/www --dir=www2:~/project2/www
|
||||
```
|
||||
|
||||
Note that the first parameter in each `--dir` argument must be unique, otherwise only the last `--dir` argument using that name will be used.
|
||||
|
||||
Note: to use the directory mounting feature, the host needs to run macOS 13.0 (Ventura) or newer.
|
||||
|
||||
### Accessing mounted directories in macOS guests
|
||||
|
||||
All shared directories are automatically mounted to `/Volumes/My Shared Files` directory.
|
||||
|
||||
The directory we've mounted above will be accessible from the `/Volumes/My Shared Files/project` path inside a guest VM.
|
||||
|
||||
Note: to use the directory mounting feature, the guest VM needs to run macOS 13.0 (Ventura) or newer.
|
||||
|
||||
### Accessing mounted directories in Linux guests
|
||||
|
||||
To be able to access the shared directories from the Linux guest, you need to manually mount the virtual filesystem first:
|
||||
|
||||
```shell
|
||||
mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared
|
||||
```
|
||||
|
||||
The directory we've mounted above will be accessible from the `/mnt/shared/project` path inside a guest VM.
|
||||
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
User-agent: *
|
||||
Allow: *
|
||||
Disallow:
|
||||
Sitemap: https://tart.run/sitemap.xml
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
/* Remove default title on the page */
|
||||
.md-content__inner h1:first-child {
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* Adjust to 2px to align with the title */
|
||||
.md-logo {
|
||||
padding-top: 6px;
|
||||
}
|
||||
|
||||
.btn {
|
||||
border: none;
|
||||
padding: 14px 28px;
|
||||
cursor: pointer;
|
||||
display: inline-block;
|
||||
|
||||
background: #009688;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.btn:hover {
|
||||
background: #00bfa5;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.center {
|
||||
display: block;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
}
|
||||
|
||||
.text-center {
|
||||
text-align: center;
|
||||
}
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
.tx-container {
|
||||
background:
|
||||
linear-gradient(to bottom, var(--md-primary-fg-color), var(--md-default-bg-color) 100%)
|
||||
}
|
||||
|
||||
[data-md-color-scheme=slate] .tx-container {
|
||||
background:
|
||||
linear-gradient(to bottom, var(--md-primary-fg-color), var(--md-default-bg-color) 100%)
|
||||
}
|
||||
|
||||
.tx-landing {
|
||||
margin: 0 .8rem;
|
||||
color: var(--md-primary-bg-color)
|
||||
}
|
||||
|
||||
.tx-landing h1 {
|
||||
margin-bottom: 1rem;
|
||||
color: currentColor;
|
||||
font-weight: 700
|
||||
}
|
||||
|
||||
@media screen and (max-width: 30em) {
|
||||
.tx-landing h1 {
|
||||
font-size: 1.4rem
|
||||
}
|
||||
}
|
||||
|
||||
.tx-landing__content p a {
|
||||
color: inherit;
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.tx-landing__testimonials {
|
||||
width: 100%;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.tx-landing__content p a:hover {
|
||||
color: darkblue;
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.tx-landing__logos {
|
||||
display: flex;
|
||||
flex-direction: row;
|
||||
flex-wrap: wrap;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.tx-landing__logos img {
|
||||
height: 8vh;
|
||||
max-height: 81px; /* max height of images */
|
||||
width: auto;
|
||||
margin: 2vh;
|
||||
vertical-align: middle;
|
||||
}
|
||||
|
||||
.tx-landing__quotes {
|
||||
padding-bottom: 5em;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 60em) {
|
||||
.tx-landing__quotes {
|
||||
margin: 1em 5em;
|
||||
}
|
||||
}
|
||||
|
||||
.tx-landing__quotes figure {
|
||||
margin: 2em auto 2em auto;
|
||||
}
|
||||
|
||||
.tx-landing__quote {
|
||||
display: flex;
|
||||
border-radius: 1em;
|
||||
padding: 1em 1em 0 1em;
|
||||
background: var(--md-primary-fg-color);
|
||||
}
|
||||
|
||||
.tx-landing__quote blockquote {
|
||||
border: 0;
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
.tx-landing__quote a img {
|
||||
height: 6vh;
|
||||
max-height: 81px; /* max height of images */
|
||||
display: block;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 60em) {
|
||||
.tx-container {
|
||||
padding-bottom: 14vw
|
||||
}
|
||||
|
||||
.tx-landing {
|
||||
display: flex;
|
||||
align-items: stretch
|
||||
}
|
||||
|
||||
.tx-landing__content {
|
||||
max-width: 19rem;
|
||||
margin-top: 3.5rem;
|
||||
}
|
||||
|
||||
.tx-landing__image {
|
||||
order: 1;
|
||||
width: 38rem;
|
||||
transform: translateX(4rem)
|
||||
}
|
||||
}
|
||||
|
||||
@media screen and (min-width: 77em) {
|
||||
.tx-landing__image {
|
||||
transform: translateX(8rem)
|
||||
}
|
||||
}
|
||||
|
||||
.tx-landing .md-button {
|
||||
margin-top: .5rem;
|
||||
margin-right: .5rem;
|
||||
color: var(--md-primary-bg-color)
|
||||
}
|
||||
|
||||
.tx-landing .md-button:hover, .tx-landing .md-button:focus {
|
||||
color: var(--md-default-bg-color);
|
||||
background-color: var(--md-default-fg-color);
|
||||
border-color: var(--md-default-fg-color)
|
||||
}
|
||||
|
|
@ -0,0 +1,90 @@
|
|||
{% extends "base.html" %}
|
||||
|
||||
<!-- Render landing page under tabs -->
|
||||
{% block tabs %}
|
||||
{{ super() }}
|
||||
|
||||
<!-- Additional styles for landing page -->
|
||||
<style>
|
||||
|
||||
/* Application header should be static for the landing page */
|
||||
.md-header {
|
||||
position: initial;
|
||||
}
|
||||
|
||||
/* Remove spacing, as we cannot hide it completely */
|
||||
.md-main__inner {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
/* Hide main content for now */
|
||||
.md-content {
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* Hide table of contents */
|
||||
@media screen and (min-width: 60em) {
|
||||
.md-sidebar--secondary {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
/* Hide navigation */
|
||||
@media screen and (min-width: 76.25em) {
|
||||
.md-sidebar--primary {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
<!-- landing page for landing page -->
|
||||
<section class="tx-container">
|
||||
<div class="md-grid md-typeset">
|
||||
<div class="tx-landing">
|
||||
<!-- landing image -->
|
||||
<div class="tx-landing__image">
|
||||
<script src="https://unpkg.com/@dotlottie/player-component@latest/dist/dotlottie-player.js"></script>
|
||||
<dotlottie-player
|
||||
src="/assets/animations/TartLogo.lottie"
|
||||
mode="normal"
|
||||
style="width: 75%; margin: auto;"
|
||||
autoplay
|
||||
/>
|
||||
</div>
|
||||
|
||||
<!-- landing content -->
|
||||
<div class="tx-landing__content">
|
||||
<h2><strong>Tart</strong> is a virtualization toolset to build, run and manage <i>macOS</i> and <i>Linux</i> virtual machines on <i>Apple Silicon.</i></h2>
|
||||
<p>
|
||||
Tart utilizes <i>Virtualization.Framework</i> to achieve nearly native performance.
|
||||
Benefit from clean ephemeral environments for your automations with no performance implications.
|
||||
</p>
|
||||
<p>
|
||||
For storing virtual machine images Tart integrates with OCI-compatible container registries.
|
||||
Push and pull virtual machines like you used to with Docker containers.
|
||||
</p>
|
||||
<p>
|
||||
Tart powers several continuous integration systems including <a href="/github-actions">on-demand GitHub Actions</a>
|
||||
and <a href="https://cirrus-ci.org/guide/macOS/">Cirrus CI</a>. Tart can be easily <a href="/cirrus-cli">integrated with any other CI</a>
|
||||
and soon will get <a href="https://github.com/cirruslabs/tart/issues/372">clustering capabilities</a>
|
||||
to orchestrate virtual machines on multiple physical hosts.
|
||||
</p>
|
||||
<a
|
||||
href="/quick-start"
|
||||
title="Quick Start"
|
||||
class="md-button"
|
||||
>
|
||||
Learn More
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
{% endblock %}
|
||||
|
||||
<!-- Content -->
|
||||
{% block content %}{% endblock %}
|
||||
|
||||
<!-- Application footer -->
|
||||
{% block footer %}{% endblock %}
|
||||
|
||||
|
|
@ -0,0 +1,140 @@
|
|||
---
|
||||
hide:
|
||||
- navigation
|
||||
---
|
||||
|
||||
# Managing Virtual Machine
|
||||
|
||||
## Creating from scratch
|
||||
|
||||
Tart supports macOS and Linux virtual machines. All commands like `run` and `pull` work the same way regarding of the underlying OS a particular VM image has.
|
||||
The only difference is how such VM images are created. Please check sections below for [macOS](#creating-a-macos-vm-image-from-scratch) and [Linux](#creating-a-linux-vm-image-from-scratch) instructions.
|
||||
|
||||
### Creating a macOS VM image 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.
|
||||
|
||||
### Creating a Linux VM image from scratch
|
||||
|
||||
Linux VMs are supported on hosts running macOS 13.0 (Ventura) or newer.
|
||||
|
||||
```shell
|
||||
# Create a bare VM
|
||||
tart create --linux ubuntu
|
||||
|
||||
# Install Ubuntu
|
||||
tart run --disk focal-desktop-arm64.iso ubuntu
|
||||
|
||||
# Run VM
|
||||
tart run ubuntu
|
||||
```
|
||||
|
||||
After the initial setup please make sure your VM can be SSH-ed into by running the following commands inside your VM:
|
||||
|
||||
```shell
|
||||
sudo apt update
|
||||
sudo apt install -y openssh-server
|
||||
sudo ufw allow ssh
|
||||
```
|
||||
|
||||
## 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 repository](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:
|
||||
|
||||
```hcl
|
||||
packer {
|
||||
required_plugins {
|
||||
tart = {
|
||||
version = ">= 0.5.3"
|
||||
source = "github.com/cirruslabs/tart"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
source "tart-cli" "tart" {
|
||||
vm_base_name = "ghcr.io/cirruslabs/macos-ventura-base:latest"
|
||||
vm_name = "my-custom-ventura"
|
||||
cpu_count = 4
|
||||
memory_gb = 8
|
||||
disk_size_gb = 70
|
||||
ssh_password = "admin"
|
||||
ssh_timeout = "120s"
|
||||
ssh_username = "admin"
|
||||
}
|
||||
|
||||
build {
|
||||
sources = ["source.tart-cli.tart"]
|
||||
|
||||
provisioner "shell" {
|
||||
inline = ["echo 'Disabling spotlight indexing...'", "sudo mdutil -a -i off"]
|
||||
}
|
||||
|
||||
# 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.
|
||||
|
||||
In addition, Tart supports [Docker credential helpers](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers)
|
||||
if defined in `~/.docker/config.json`.
|
||||
|
||||
Finally, `TART_REGISTRY_USERNAME` and `TART_REGISTRY_PASSWORD` environment variables allow to override authorization
|
||||
for all registries which might useful for integrating with your CI's secret management.
|
||||
|
||||
### 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
|
||||
|
||||
You can either pull an image:
|
||||
|
||||
```shell
|
||||
tart pull acme.io/remoteorg/name:latest
|
||||
```
|
||||
|
||||
...or instantiate a VM from a remote image:
|
||||
|
||||
```shell
|
||||
tart clone acme.io/remoteorg/name:latest my-local-vm-name
|
||||
```
|
||||
|
||||
This invocation calls the `tart pull` implicitly (if the image is not being present) before doing the actual cloning.
|
||||
|
|
@ -0,0 +1,98 @@
|
|||
repo_url: https://github.com/cirruslabs/tart/
|
||||
site_url: https://tart.run/
|
||||
edit_uri: blob/main/docs/
|
||||
|
||||
site_name: Tart
|
||||
site_author: Cirrus Labs
|
||||
copyright: © Cirrus Labs 2017-present
|
||||
site_description: >
|
||||
Tart is a virtualization toolset to build, run and manage macOS and Linux virtual machines (VMs) on Apple Silicon.
|
||||
Built by CI engineers for your automation needs.
|
||||
|
||||
remote_branch: main
|
||||
|
||||
theme:
|
||||
name: 'material'
|
||||
custom_dir: 'docs/theme'
|
||||
favicon: 'assets/images/favicon.ico'
|
||||
logo: 'assets/images/TartLogo.webp'
|
||||
icon:
|
||||
repo: fontawesome/brands/github
|
||||
language: en
|
||||
palette:
|
||||
- scheme: default
|
||||
primary: orange
|
||||
accent: orange
|
||||
font:
|
||||
text: Roboto
|
||||
code: Roboto Mono
|
||||
features:
|
||||
- announce.dismiss
|
||||
- content.tabs.link
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- navigation.top
|
||||
- search.suggest
|
||||
- toc.follow
|
||||
|
||||
extra_css:
|
||||
- 'stylesheets/extra.css'
|
||||
- 'stylesheets/landing.css'
|
||||
|
||||
plugins:
|
||||
- search
|
||||
- minify
|
||||
|
||||
markdown_extensions:
|
||||
- markdown.extensions.admonition
|
||||
- markdown.extensions.codehilite:
|
||||
guess_lang: false
|
||||
- markdown.extensions.def_list
|
||||
- markdown.extensions.footnotes
|
||||
- markdown.extensions.meta
|
||||
- markdown.extensions.toc:
|
||||
permalink: true
|
||||
- pymdownx.arithmatex
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
- pymdownx.caret
|
||||
- pymdownx.critic
|
||||
- pymdownx.details
|
||||
- pymdownx.emoji:
|
||||
emoji_generator: !!python/name:pymdownx.emoji.to_svg
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- pymdownx.superfences
|
||||
- pymdownx.keys
|
||||
- pymdownx.magiclink
|
||||
- pymdownx.mark
|
||||
- pymdownx.smartsymbols
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- pymdownx.tilde
|
||||
|
||||
nav:
|
||||
- "Home": index.md
|
||||
- "Quick Start": quick-start.md
|
||||
- "GitHub Actions": github-actions.md
|
||||
- "Self-hosted CI": cirrus-cli.md
|
||||
- "Managing VMs": vm-management.md
|
||||
|
||||
extra:
|
||||
analytics:
|
||||
provider: google
|
||||
property: G-HXBEB9D47X
|
||||
consent:
|
||||
title: Cookie consent
|
||||
description: >-
|
||||
We use cookies to recognize your repeated visits and preferences, as well
|
||||
as to measure the effectiveness of our documentation and whether users
|
||||
find what they're searching for. With your consent, you're helping us to
|
||||
make our documentation better.
|
||||
social:
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: 'https://twitter.com/cirrus_labs'
|
||||
Loading…
Reference in New Issue