diff --git a/.cirrus.yml b/.cirrus.yml index 1b9d378..6fbc320 100644 --- a/.cirrus.yml +++ b/.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 diff --git a/.gitattributes b/.gitattributes index 4a9d8e8..54750d4 100644 --- a/.gitattributes +++ b/.gitattributes @@ -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 diff --git a/README.md b/README.md index f6e2051..f88607b 100644 --- a/README.md +++ b/README.md @@ -48,277 +48,8 @@ tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base tart run ventura-base ``` - - -## 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//settings/actions/runners`. - - - -### 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 -``` - - - -[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 ``` - -
- How to connect to a VM over SSH? - - 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) - ``` -
diff --git a/Resources/TartSocial.png b/Resources/TartSocial.png index 89de7d7..c3eabba 100644 --- a/Resources/TartSocial.png +++ b/Resources/TartSocial.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:769dcd5411f44071cb46f63459118fef728c866a581cf94a28811f407ca9827d -size 606936 +oid sha256:18ff880508365cea59c5538ab8f1593093436c3f0eec42ca0504f806e7b5dcc0 +size 582270 diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..0275f08 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1,2 @@ +tart.run +www.tart.run diff --git a/docs/assets/animations/TartLogo.lottie b/docs/assets/animations/TartLogo.lottie new file mode 100644 index 0000000..f2ce828 --- /dev/null +++ b/docs/assets/animations/TartLogo.lottie @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1d9cef166b57d57e29b1821fbc06ea2ea5ac92cf29d526ce17c88b9942d2d89d +size 7392 diff --git a/docs/assets/images/CirrusLogo.svg b/docs/assets/images/CirrusLogo.svg new file mode 100644 index 0000000..5ff9d21 --- /dev/null +++ b/docs/assets/images/CirrusLogo.svg @@ -0,0 +1,15 @@ + + + cirrus-logo + + + + + diff --git a/Resources/TartCirrusCLI.gif b/docs/assets/images/TartCirrusCLI.gif similarity index 100% rename from Resources/TartCirrusCLI.gif rename to docs/assets/images/TartCirrusCLI.gif diff --git a/Resources/TartGHARunners.png b/docs/assets/images/TartGHARunners.png similarity index 100% rename from Resources/TartGHARunners.png rename to docs/assets/images/TartGHARunners.png diff --git a/docs/assets/images/TartLogo.webp b/docs/assets/images/TartLogo.webp new file mode 100644 index 0000000..a5a7ed4 Binary files /dev/null and b/docs/assets/images/TartLogo.webp differ diff --git a/docs/assets/images/favicon.ico b/docs/assets/images/favicon.ico new file mode 100644 index 0000000..0ed757e --- /dev/null +++ b/docs/assets/images/favicon.ico @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6e3985ec2459dfe94f3a761cbe4bb6895096650950ab0bf7f8ab4b6338c0a915 +size 15406 diff --git a/docs/cirrus-cli.md b/docs/cirrus-cli.md new file mode 100644 index 0000000..a23c239 --- /dev/null +++ b/docs/cirrus-cli.md @@ -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 +``` + +![](/assets/images/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`. diff --git a/docs/github-actions.md b/docs/github-actions.md new file mode 100644 index 0000000..46d9415 --- /dev/null +++ b/docs/github-actions.md @@ -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//settings/actions/runners`. + +![](/assets/images/TartGHARunners.png) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b2d8d98 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,4 @@ +--- +template: overrides/home.html +title: Tart +--- diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..cff9edd --- /dev/null +++ b/docs/quick-start.md @@ -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 +``` + +

+ +

+ +## 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. + diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 0000000..5eaa492 --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: * +Disallow: +Sitemap: https://tart.run/sitemap.xml diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..ede6e61 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -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; +} diff --git a/docs/stylesheets/landing.css b/docs/stylesheets/landing.css new file mode 100644 index 0000000..f24b281 --- /dev/null +++ b/docs/stylesheets/landing.css @@ -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) +} diff --git a/docs/theme/overrides/home.html b/docs/theme/overrides/home.html new file mode 100644 index 0000000..05e1053 --- /dev/null +++ b/docs/theme/overrides/home.html @@ -0,0 +1,90 @@ +{% extends "base.html" %} + + +{% block tabs %} +{{ super() }} + + + + + +
+
+
+ +
+ + +
+ + +
+

Tart is a virtualization toolset to build, run and manage macOS and Linux virtual machines on Apple Silicon.

+

+ Tart utilizes Virtualization.Framework to achieve nearly native performance. + Benefit from clean ephemeral environments for your automations with no performance implications. +

+

+ For storing virtual machine images Tart integrates with OCI-compatible container registries. + Push and pull virtual machines like you used to with Docker containers. +

+

+ Tart powers several continuous integration systems including on-demand GitHub Actions + and Cirrus CI. Tart can be easily integrated with any other CI + and soon will get clustering capabilities + to orchestrate virtual machines on multiple physical hosts. +

+ + Learn More + +
+
+
+
+{% endblock %} + + +{% block content %}{% endblock %} + + +{% block footer %}{% endblock %} + diff --git a/docs/vm-management.md b/docs/vm-management.md new file mode 100644 index 0000000..4cfec3a --- /dev/null +++ b/docs/vm-management.md @@ -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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d7bf148 --- /dev/null +++ b/mkdocs.yml @@ -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'