vagrant_utm 0.0.1

data/docs/README.md

@@ -0,0 +1,174 @@
+# just-the-docs-template
+
+This is a *bare-minimum* template to create a [Jekyll] site that:
+
+- uses the [Just the Docs] theme;
+- can be built and published on [GitHub Pages];
+- can be built and previewed locally, and published on other platforms.
+
+More specifically, the created site:
+
+- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem;
+- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages.
+
+To get started with creating a site, simply:
+
+1. click "[use this template]" to create a GitHub repository
+2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions
+
+If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](#hosting-your-docs-from-an-existing-project-repo).
+
+After completing the creation of your new site on GitHub, update it as needed:
+
+## Replace the content of the template pages
+
+Update the following files to your own content:
+
+- `index.md` (your new home page)
+- `README.md` (information for those who access your site repo on GitHub)
+
+## Changing the version of the theme and/or Jekyll
+
+Simply edit the relevant line(s) in the `Gemfile`.
+
+## Adding a plugin
+
+The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin.
+
+To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]:
+
+- Add the following to your site's `Gemfile`:
+
+  ```ruby
+  gem "jekyll-default-layout"
+  ```
+
+- And add the following to your site's `_config.yml`:
+
+  ```yaml
+  plugins:
+    - jekyll-default-layout
+  ```
+
+Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
+
+## Publishing your site on GitHub Pages
+
+1.  If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to:
+
+    ```yaml
+    title: YOUR TITLE
+    description: YOUR DESCRIPTION
+    theme: just-the-docs
+
+    url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME
+
+    aux_links: # remove if you don't want this link to appear on your pages
+      Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME
+    ```
+
+2.  Push your updated `_config.yml` to your site on GitHub.
+
+3.  In your newly created repo on GitHub:
+    - go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`.
+    - if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`.
+
+## Building and previewing your site locally
+
+Assuming [Jekyll] and [Bundler] are installed on your computer:
+
+1.  Change your working directory to the root directory of your site.
+
+2.  Run `bundle install`.
+
+3.  Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`.
+
+    The built site is stored in the directory `_site`.
+
+## Publishing your built site on a different platform
+
+Just upload all the files in the directory `_site`.
+
+## Customization
+
+You're free to customize sites that you create with this template, however you like!
+
+[Browse our documentation][Just the Docs] to learn more about how to use this theme.
+
+## Hosting your docs from an existing project repo
+
+You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/just-the-docs-template), you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a `docs` directory. You can clone the template to your local machine or download the `.zip` file to access the files.
+
+### Copy the template files
+
+1.  Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files.
+
+2.  Create a `docs` directory at your project root and copy all remaining template files into this directory.
+
+### Modify the GitHub Actions workflow
+
+The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the `pages.yml` file. You'll need to edit this file to that so that your build and deploy steps look to your `docs` directory, rather than the project root.
+
+1.  Set the default `working-directory` param for the build job.
+
+    ```yaml
+    build:
+      runs-on: ubuntu-latest
+      defaults:
+        run:
+          working-directory: docs
+    ```
+
+2.  Set the `working-directory` param for the Setup Ruby step.
+
+    ```yaml
+    - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: '${{ github.workspace }}/docs'
+    ```
+
+3.  Set the path param for the Upload artifact step:
+
+    ```yaml
+    - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: "docs/_site/"
+    ```
+
+4.  Modify the trigger so that only changes within the `docs` directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy.
+
+    ```yaml
+    on:
+      push:
+        branches:
+          - "main"
+        paths:
+          - "docs/**"
+    ```
+
+## Licensing and Attribution
+
+This repository is licensed under the [MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!
+
+The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows]. A copy of their MIT License is available in [actions/starter-workflows].
+
+----
+
+[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
+
+[Jekyll]: https://jekyllrb.com
+[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
+[GitHub Pages]: https://docs.github.com/en/pages
+[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
+[Bundler]: https://bundler.io
+[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate
+[`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout
+[`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag
+[MIT License]: https://en.wikipedia.org/wiki/MIT_License
+[starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml
+[actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE

data/docs/_config.yml

@@ -0,0 +1,76 @@
+title: Vagrant UTM
+description: >-
+  vagrant_utm is a Vagrant plugin which adds UTM provider to Vagrant, 
+  allowing Vagrant to control and provision machines via UTM's API
+baseurl: "/docs" # the subpath of your site, e.g. /blog
+# theme: just-the-docs
+
+url: "https://naveenrajm7.github.io/vagrant_utm"
+github_username:  naveenrajm7
+repository: naveenrajm7/vagrant_utm
+
+# Build settings
+remote_theme: just-the-docs/just-the-docs@v0.8.2
+plugins:
+  - jekyll-remote-theme
+
+# Website settings
+
+logo: "/assets/images/logo.png"
+# Set a path/url to a favicon that will be displayed by the browser
+favicon_ico: "/assets/images/logo.png"
+
+heading_anchors: true
+
+nav_external_links:
+  - title: Vagrant
+    url: https://www.vagrantup.com
+  - title: UTM for macOS
+    url: https://mac.getutm.app
+  - title: Packer plugin for UTM
+    url: https://github.com/naveenrajm7/packer-plugin-utm
+  # - title: GitHub
+  #   url: https://github.com/naveenrajm7/vagrant_utm
+
+
+# Aux links for the upper right navigation
+aux_links:
+  "Vagrant UTM on GitHub":
+    - "//github.com/naveenrajm7/vagrant_utm"
+
+# Edit on Github
+gh_edit_link: true
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/naveenrajm7/vagrant_utm"
+gh_edit_branch: "main"
+gh_edit_source: "docs"
+gh_edit_view_mode: "tree"
+
+
+# callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+# For copy button on code
+enable_copy_code_button: true
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Footer
+footer_content: "Copyright &copy; 2024 Naveenraj Muthuraj. Distributed by an <a href=\"https://github.com/naveenrajm7/vagrant_utm/tree/main/LICENSE.txt\">MIT license.</a>"

data/docs/_includes/footer_custom.html

@@ -0,0 +1,3 @@
+{%- if site.footer_content -%}
+  <p class="text-small text-grey-dk-100 mb-0">{{ site.footer_content }}</p>
+{%- endif -%}

data/docs/_sass/gallery.scss

@@ -0,0 +1,64 @@
+.gallery {
+  display: flex;
+  flex-flow: row wrap;
+  justify-content: center;
+  align-items: center;
+}
+
+.gallery .gallery-item {
+  padding: 5px;
+  width: 20em;
+}
+
+.gallery-item a {
+  text-decoration: none;
+  color: black;
+}
+
+.gallery h3, .gallery h4 {
+  text-align: center;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.gallery h3 {
+  font-size: 1.2em;
+}
+
+.gallery h4 {
+  margin: 10px 0 10px 0;
+  font-size: 0.8em;
+  font-weight: normal;
+}
+
+.gallery .image {
+  width: 20em;
+}
+
+.gallery .screenshot {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  box-shadow: 0 1px 0 #ccc, 0 1px 0 1px #eee;
+  border-radius: 2px;
+  margin-left: auto;
+  margin-right: auto;
+  background: #DDD url('data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2244%22%20height%3D%2212%22%20viewBox%3D%220%200%2044%2012%22%3E%3Ccircle%20cx%3D%226%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3Ccircle%20cx%3D%2222%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3Ccircle%20cx%3D%2238%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3C%2Fsvg%3E') 4px 4px no-repeat;
+  padding: 20px 0 0 0;
+  position: relative;
+}
+
+.gallery .placeholder {
+  padding-top: 75%;
+}
+
+.gallery li {
+  padding: 5px 0 5px 0;
+}
+
+.gallery .button {
+  padding-bottom: 5px;
+  margin: 20px 0 20px 0;
+  font-size: 1.5em;
+}

data/docs/_virtual_machines/archlinux-arm.md

@@ -0,0 +1,13 @@
+---
+title: ArchLinux ARM
+architecture: ARM64
+memory: 2048 MiB
+disk: 10 GiB
+display: Console
+spice_installed: false
+username: root
+password: root
+screenshot: archlinux-logo.png
+download: https://github.com/utmapp/vm-downloads/releases/download/archlinux-arm64/archlinux-arm64-utm4.zip
+utm_link: true
+---

data/docs/boxes/creating_utm_box.md

@@ -0,0 +1,70 @@
+---
+title: Creating a UTM box
+parent: UTM Box
+nav_order: 2
+---
+
+# Creating a UTM Base Box
+
+As with [every Vagrant Provider](https://developer.hashicorp.com/vagrant/docs/providers/basic_usage), the Vagrant UTM provider has a custom box format that is required to work with Vagrant and the UTM plugin.
+
+{: .important }
+The UTM bundle (.utm file) is the box format for Vagrant UTM provider. 
+Because the current UTM API does not support importing utm file, we do not use vagrant box format (.box file).
+We currently use `utm://downloadVM?url=` to import VM to UTM.
+
+
+{: .note }
+However, once UTM supports import, we should be able to package UTM files into box format and use the benefits of Vagrant boxes . For example, downloading the box once to spin up multiple VMs and using vagrant cloud to publish custom UTM boxes.
+
+
+{: .warning } 
+This is a reasonably advanced topic that a beginning user of Vagrant does not need to understand. If you are just getting started with Vagrant, skip this and use an [available box](/utm_box_gallery.md). If you are an experienced user of Vagrant and want to create your own custom boxes, this is for you.
+
+## Virtual Machine
+
+The virtual machine created in UTM can use any configuration you would like, but Vagrant has some hard requirements:
+
+* The second network interface (adapter 1 or index 1) must be a `Emulated VLAN` adapter. Vagrant uses this to connect the first time.
+
+* Use can use the first network interface (adapter 0 or index 0) to be `Shared Network`, which is recommended for new virtual machines. 
+
+Other than the above, you are free to customize the base virtual machine as you see fit.
+
+## Additional Software
+
+In addition to the software that should be installed based on the [general guide to creating base boxes](https://developer.hashicorp.com/vagrant/docs/boxes/base), UTM base boxes require some additional software.
+
+### UTM Guest Support
+
+In order to take full advantage of all the features UTM has to offer, you need to install some software in the virtual machine guest.
+
+Check the [UTM Guide on Guest Support](https://docs.getutm.app/guest-support/guest-support/) to install software based on your guest operating system.
+
+## Building your own UTM boxes
+
+By satisfying the [general guidance on creating vagrant boxes](https://developer.hashicorp.com/vagrant/docs/boxes/base) and the above [Virtual Machine](#virtual-machine) requirements you can use your VM with Vagrant UTM plugin.
+
+Apart from manually building the boxes, you can also use the semi-automated way of building these boxes using [packer plugin for UTM](https://github.com/naveenrajm7/packer-plugin-utm).
+The packer plugin has a builder and a post processor, which uses an existing UTM file, adds Vagrant specific stuff and packs the UTM file as a zip so it can be used by UTM Vagrant plugin.
+
+Checkout [UTM Box Guide](https://github.com/naveenrajm7/utm-box/blob/main/HowToBuild/DebianUTM.md) to know how to build Box using packer.
+
+## Using your own UTM boxes
+
+Due to the limitation of UTM API, the plugin can only take a url pointing to the zip file.
+So, you can use a local python server to host your UTM bundle in zip file
+
+```bash
+python3 -m http.server                                                                            
+Serving HTTP on :: port 8000 (http://[::]:8000/) ...
+```
+
+Use in Vagrantfile
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provider :utm do |utm|
+    utm.utm_file_url = "http://localhost:8000/debian_vagrant_utm.zip"
+  end
+end
+```

data/docs/boxes/index.md

@@ -0,0 +1,6 @@
+---
+title: UTM Box
+nav_order: 5
+has_children: true
+---
+

data/docs/boxes/utm_box_gallery.md

@@ -0,0 +1,117 @@
+---
+title: UTM box gallery
+# layout: default
+parent: UTM Box
+nav_order: 1
+---
+
+# UTM Box Gallery
+
+To work with Vagrant, a base VM (box) must have 
+[certain features](https://developer.hashicorp.com/vagrant/docs/boxes/base), like a ssh user for vagrant to connect.
+
+To help you get started with Vagrant UTM provider, couple of pre-built VMs from the [UTM Gallery](https://mac.getutm.app/gallery/) are modified to work with Vagrant and are made available to use.
+
+
+* Debian 11 (Xfce):   
+```ruby
+u.utm_file_url = https://github.com/naveenrajm7/utm-box/releases/download/debian-11/debian_vagrant_utm.zip 
+```
+
+<!-- * ArchLinux ARM -->
+
+
+{: .new}
+To enable building reproducible and easily sharable UTM VM bundle a [packer plugin for UTM](https://github.com/naveenrajm7/packer-plugin-utm) has been developed.
+Please see the [UTM Box Guide](https://github.com/naveenrajm7/utm-box/blob/main/HowToBuild/DebianUTM.md) on how these UTM Vagrant boxes were built using packer.
+
+
+Check out [Creating UTM Box](/boxes/creating_utm_box.md) to build your own Vagrant compatible UTM box.
+
+## Corresponding VMs from UTM Gallery
+
+<div class="content">
+  <section class="gallery">
+      <!-- <div class="gallery-item">
+          <a href="{{ vm.url }}">
+              <h3>ArchLinux ARM</h3>
+              <h4><i class="fas fa-microchip"></i> ARM64 </h4>
+              <img src="{{ site.baseurl }}/assets/images/screens/archlinux-logo.png" alt="Screenshot" class="screenshot" />
+          </a>
+      </div> -->
+      <div class="gallery-item">
+        <a href="">
+            <h3>Debian 11 (Xfce)</h3>
+            <h4><i class="fas fa-microchip"></i> ARM64 </h4>
+            <img src="{{ site.baseurl }}/assets/images/screens/debian-11-xfce-arm64.png" alt="Screenshot" class="screenshot" />
+        </a>
+      </div>
+  </section>
+</div>
+
+<style>
+.gallery {
+  display: flex;
+  flex-flow: row wrap;
+  justify-content: center;
+  align-items: center;
+}
+
+.gallery .gallery-item {
+  padding: 5px;
+  width: 20em;
+}
+
+.gallery-item a {
+  text-decoration: none;
+  color: black;
+}
+
+.gallery h3, .gallery h4 {
+  text-align: center;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.gallery h3 {
+  font-size: 1.2em;
+}
+
+.gallery h4 {
+  margin: 10px 0 10px 0;
+  font-size: 0.8em;
+  font-weight: normal;
+}
+
+.gallery .image {
+  width: 20em;
+}
+
+.gallery .screenshot {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  box-shadow: 0 1px 0 #ccc, 0 1px 0 1px #eee;
+  border-radius: 2px;
+  margin-left: auto;
+  margin-right: auto;
+  background: #DDD url('data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2244%22%20height%3D%2212%22%20viewBox%3D%220%200%2044%2012%22%3E%3Ccircle%20cx%3D%226%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3Ccircle%20cx%3D%2222%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3Ccircle%20cx%3D%2238%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3C%2Fsvg%3E') 4px 4px no-repeat;
+  padding: 20px 0 0 0;
+  position: relative;
+}
+
+.gallery .placeholder {
+  padding-top: 75%;
+}
+
+.gallery li {
+  padding: 5px 0 5px 0;
+}
+
+.gallery .button {
+  padding-bottom: 5px;
+  margin: 20px 0 20px 0;
+  font-size: 1.5em;
+}
+</style>

data/docs/commands.md

@@ -0,0 +1,156 @@
+---
+layout: default
+title: Commands (CLI)
+nav_order: 2
+---
+
+# Commands (CLI)
+{: .no_toc }
+
+This page lists all the supported Vagrant commands which depend on the  UTM provider. Eg. `up`, `suspend`, `resume`, `halt`.
+
+Adds note to the command which are not yet available. Eg. `package`.
+
+The Vagrant commands that do not depend on provider are not listed and will continue to work. Eg. `global-status`
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+
+---
+
+## **Box**
+
+**Command: `vagrant box`**
+
+UTM provider uses .utm file as VM bundle .
+
+Box support is not yet available.
+
+## **Destroy**
+
+**Command: `vagrant destroy [name|id]`**
+
+```utmctl delete```
+
+## **Halt**
+
+**Command: `vagrant halt [name|id]`**
+
+```utmctl stop```
+
+## **Package**
+
+**Command: `vagrant package [name|id]`**
+
+Currently prompts to manually export (Share) the VM
+
+
+
+## **Port**
+
+**Command: `vagrant port [name|id]`**
+
+The port command displays the full list of guest ports mapped to the host machine ports:
+
+
+
+## **Provision**
+
+**Command: `vagrant provision [vm-name]`**
+
+Runs any configured [provisioners](https://developer.hashicorp.com/vagrant/docs/provisioning) against the running Vagrant managed machine
+
+
+
+## **Reload**
+
+**Command: `vagrant reload [name|id]`**
+
+The equivalent of running a [halt](https://developer.hashicorp.com/vagrant/docs/cli/halt) followed by an[up](https://developer.hashicorp.com/vagrant/docs/cli/up).
+
+
+
+## **Resume**
+
+**Command: `vagrant resume [name|id]`**
+
+This resumes a Vagrant managed machine that was previously suspended, perhaps with the [suspend command](https://developer.hashicorp.com/vagrant/docs/cli/suspend).
+
+```utmctl start```
+
+
+
+## **Snapshot**
+
+**Command: `vagrant snapshot`**
+
+{: .warning }
+Snapshot feature is not available in UTM. 
+The plugin just provides experimental feature using qemu-img 
+
+Vagrant UTM provider supports offline snapshots using 
+qemu-img. Hence only VM with single qcow2 file is supported.
+
+
+
+## **SSH**
+
+**Command: `vagrant ssh [name|id] [-- extra_ssh_args]`**
+
+
+
+## **SSH Config**
+
+**Command: `vagrant ssh-config [name|id]`**
+
+
+
+## **Status**
+
+**Command: `vagrant status [name|id]`**
+
+`utmctl status`
+
+
+
+## **Suspend**
+
+**Command: `vagrant suspend [name|id]`**
+
+`utmctl suspend`
+
+
+
+## **Up**
+
+**Command: `vagrant up [name|id]`**
+
+Import VM (if not created)
+
+`utmctl start`
+
+
+
+## **Upload**
+
+**Command: `vagrant upload source [destination] [name|id]`**
+
+
+
+# **Custom Commands**
+
+These are the commands not available in vagrant but specific to UTM provider.
+
+## Disposable
+
+**Command: `vagrant disposable [name|id]`**
+
+`utmctl start --disposable`
+
+Start virtual machine in disposable mdoe, which allows you to run a virtual machine without saving any persistent changes to the drive.
+
+Read about Disposable mode in [UTM docs](https://docs.getutm.app/advanced/disposable/)