From f806b1536fe4f97eaad1cbe4a18c35ce91290135 Mon Sep 17 00:00:00 2001 From: Giulia Zanchi Date: Thu, 8 Aug 2024 12:44:38 +0200 Subject: [PATCH 1/6] Update README.md I reviewed the README text, applying some layout improvements and minor copy edits. I also added a new section, "Contributing guidelines", please provide feedback on that! Signed-off-by: Giulia Zanchi --- README.md | 122 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 80 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 83d636c4f6..11f07f4efb 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,10 @@ # What is Multipass? -Multipass is a lightweight VM manager for Linux, Windows and macOS. It's designed -for developers who want a fresh Ubuntu environment with a single command. It uses -KVM on Linux, Hyper-V on Windows and QEMU on macOS to run the VM with minimal -overhead. It can also use VirtualBox on Windows and macOS. -Multipass will fetch images for you and keep them up to date. +Multipass is a lightweight VM manager for Linux, Windows and macOS. It's designed for developers who want to spin up a fresh Ubuntu environment with a single command. It uses KVM on Linux, Hyper-V on Windows and QEMU on macOS to run virtual machines with minimal overhead. It can also use VirtualBox on Windows and macOS. Multipass will fetch Ubuntu images for you and keep them up to date. -Since it supports metadata for cloud-init, you can simulate a small cloud -deployment on your laptop or workstation. +Since it supports metadata for cloud-init, you can simulate a small cloud deployment on your laptop or workstation. -## Project Status +## Project status | Service | Status | |-----|:---| @@ -17,29 +12,35 @@ deployment on your laptop or workstation. | [Snap](https://snapcraft.io/) | [![Build Status][snap-image]][snap-url] | | [Codecov](https://codecov.io/) | [![Codecov Status][codecov-image]][codecov-url] | -# Install Multipass +# Installation -On Linux it's available as a snap: +* On **Linux**, Multipass is available as a snap: -``` -sudo snap install multipass -``` + ``` + sudo snap install multipass + ``` -For macOS, you can download the installers [from GitHub](https://github.com/canonical/multipass/releases) or [use Homebrew](https://github.com/Homebrew/brew): +* On **macOS**, you can download the installer [from GitHub](https://github.com/canonical/multipass/releases) or use [Homebrew](https://github.com/Homebrew/brew): -``` -# Note, this may require you to enter your password for some sudo operations during install -# Mac OS users may need to disable their firewall to launch a multipass instance successfully -brew install --cask multipass -``` + ``` + brew install --cask multipass + ``` + + Please note that you may be required to enter your password for some sudo operations during installation. You may also need to disable the firewall to launch a multipass instance successfully on macOS. + +* On **Windows**, download the installer [from GitHub](https://github.com/canonical/multipass/releases). -On Windows, download the installer [from GitHub](https://github.com/canonical/multipass/releases). +For more information, see [How to install Multipass](https://multipass.run/docs/install-multipass). # Usage +Here are some pointers to get started with Multipass. For a more comprehensive learning experience, please check out the Multipass [Tutorial](https://multipass.run/docs/tutorial). + ## Find available images + ``` $ multipass find + Image Aliases Version Description core core16 20200213 Ubuntu Core 16 core18 20200210 Ubuntu Core 18 @@ -50,25 +51,31 @@ daily:20.10 devel,groovy 20200721 Ubuntu 20.10 ``` ## Launch a fresh instance of the current Ubuntu LTS + ``` $ multipass launch ubuntu + Launching dancing-chipmunk... Downloading Ubuntu 18.04 LTS.......... Launched: dancing chipmunk ``` ## Check out the running instances + ``` $ multipass list + Name State IPv4 Release dancing-chipmunk RUNNING 10.125.174.247 Ubuntu 18.04 LTS live-naiad RUNNING 10.125.174.243 Ubuntu 18.04 LTS snapcraft-asciinema STOPPED -- Ubuntu Snapcraft builder for Core 18 ``` -## Learn more about the VM instance you just launched +## Learn more about an instance + ``` $ multipass info dancing-chipmunk + Name: dancing-chipmunk State: RUNNING IPv4: 10.125.174.247 @@ -84,18 +91,18 @@ Memory usage: 85.1M out of 985.4M ``` $ multipass shell dancing-chipmunk -Welcome to Ubuntu 18.04.1 LTS (GNU/Linux 4.15.0-42-generic x86_64) +Welcome to Ubuntu 18.04.1 LTS (GNU/Linux 4.15.0-42-generic x86_64) ... ``` -Don't forget to logout (or Ctrl-D) or you may find yourself heading all the -way down the Inception levels... ;) +Don't forget to logout (or Ctrl-D) or you may find yourself heading all the way down Inception levels... ;) ## Run commands inside an instance from outside ``` $ multipass exec dancing-chipmunk -- lsb_release -a + No LSB modules are available. Distributor ID: Ubuntu Description: Ubuntu 18.04.1 LTS @@ -104,40 +111,46 @@ Codename: bionic ``` ## Stop an instance to save resources + ``` $ multipass stop dancing-chipmunk ``` -## Delete the instance +## Delete an instance + ``` $ multipass delete dancing-chipmunk ``` -It will now show up as deleted: +The instance will now show up as deleted: + ```$ multipass list + Name State IPv4 Release snapcraft-asciinema STOPPED -- Ubuntu Snapcraft builder for Core 18 dancing-chipmunk DELETED -- Not Available ``` -And when you want to completely get rid of it: +If you want to completely get rid of it: ``` $ multipass purge ``` ## Get help -``` +``` multipass help multipass help ``` -# Get involved! +# Make your own build + +Here's a set of steps to make and run your own build of Multipass. -Here's a set of steps to build and run your own build of Multipass. Please note that the following instructions are for building Multipass for Linux only. These instructions do not support building packages for macOS or Windows systems. +Please note that the following instructions are for building Multipass for Linux only. These instructions do not support building packages for macOS or Windows systems. -## Build Dependencies +## Build dependencies ``` cd @@ -145,7 +158,7 @@ apt install devscripts equivs mk-build-deps -s sudo -i ``` -## Building +## Build Multipass ``` cd @@ -155,10 +168,12 @@ cd build cmake ../ make ``` -**Note:** if you're working on a forked repository that you created using the "Copy the main branch only" option, the repository will not include the necessary git tags to determine the Multipass version during CMake configuration. In this case, you need to manually fetch the tags from the upstream by running `git fetch --tags https://github.com/canonical/multipass.git` in the `` source code directory. -## Running Multipass daemon and client -First, install multipass's runtime dependencies. On amd64 architecture, you can achieve that with: +Please note that if you're working on a forked repository that you created using the "Copy the main branch only" option, the repository will not include the necessary git tags to determine the Multipass version during CMake configuration. In this case, you need to manually fetch the tags from the upstream by running `git fetch --tags https://github.com/canonical/multipass.git` in the `` source code directory. + +## Run the Multipass daemon and client + +First, install Multipass's runtime dependencies. On AMD64 architecture, you can do this with: ``` sudo apt update @@ -168,34 +183,57 @@ sudo apt install libgl1 libpng16-16 libqt6core6 libqt6gui6 \ iptables iputils-ping libatm1 libxtables12 xterm ``` -Then run multipass's daemon: +Then run the Multipass daemon: + ``` sudo /build/bin/multipassd & ``` -Copy the desktop file multipass clients expect to find in your home: +Copy the desktop file that Multipass clients expect to find in your home: ``` mkdir -p ~/.local/share/multipass/ cp /data/multipass.gui.autostart.desktop ~/.local/share/multipass/ ``` -Optionally, enable auto-complete in bash: +Optionally, enable auto-complete in Bash: ``` source /completions/bash/multipass ``` -Finally, use multipass's clients: +Finally, launch the Multipass clients: ``` /build/bin/multipass launch --name foo # CLI client -/build/bin/multipass.gui # GUI client +/build/bin/multipass.gui # GUI client ``` -# More information +# Contributing guidelines + +The Multipass team appreciates contributions to the project, through pull requests, issues, or discussions and questions on the [Discourse forum](https://discourse.ubuntu.com/c/multipass/21). + +Please read the following guidelines carefully before contributing to the project. + +## Code of Conduct + +When contributing, you must adhere to the [Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct). + +## Copyright + +The code in this repository is licensed under GNU General Public License v3.0. See [LICENSE](https://github.com/canonical/multipass/blob/main/LICENSE) for more information. + +## License agreement + +All contributors must sign the [Canonical contributor license agreement (CLA)](https://ubuntu.com/legal/contributors), which gives Canonical permission to use the contributions. Without the CLA, contributions cannot be accepted. + +## Pull requests + +Changes to this project should be proposed as pull requests. Proposed changes will then go through review and once approved, be merged into the main branch. + +# Additional information -See [the Multipass documentation](https://discourse.ubuntu.com/c/multipass/doc). +[Multipass documentation](https://multipass.run/docs) [gha-image]: https://github.com/canonical/multipass/workflows/Linux/badge.svg?branch=main [gha-url]: https://github.com/canonical/multipass/actions?query=branch%3Amain+workflow%3ALinux From 344cef644681dffc74cf25edb9166441811256a0 Mon Sep 17 00:00:00 2001 From: Giulia Zanchi Date: Mon, 12 Aug 2024 11:16:11 +0200 Subject: [PATCH 2/6] Update README.md I've applied all the fixes suggested by the team (thanks Andrei, Jia and Scott!). Please review and see if it's all good now. I have also been testing the instructions to Multipass, they need some debugging. For now I'll leave the contributing info as a subsection of the Readme, but let's consider the possibility of having it as a separate file as it's done on other projects. Signed-off-by: Giulia Zanchi --- README.md | 86 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 11f07f4efb..56254e82dd 100644 --- a/README.md +++ b/README.md @@ -42,22 +42,26 @@ Here are some pointers to get started with Multipass. For a more comprehensive l $ multipass find Image Aliases Version Description -core core16 20200213 Ubuntu Core 16 -core18 20200210 Ubuntu Core 18 -16.04 xenial 20200721 Ubuntu 16.04 LTS -18.04 bionic,lts 20200717 Ubuntu 18.04 LTS -20.04 focal 20200720 Ubuntu 20.04 LTS -daily:20.10 devel,groovy 20200721 Ubuntu 20.10 +20.04 focal 20240731 Ubuntu 20.04 LTS +22.04 jammy 20240808 Ubuntu 22.04 LTS +24.04 noble,lts 20240806 Ubuntu 24.04 LTS + +Blueprint Aliases Version Description +anbox-cloud-appliance latest Anbox Cloud Appliance +charm-dev latest A development and testing environment for charmers +docker 0.4 A Docker environment with Portainer and related tools +jellyfin latest Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media. +minikube latest minikube is local Kubernetes +ros-noetic 0.1 A development and testing environment for ROS Noetic. +ros2-humble 0.1 A development and testing environment for ROS 2 Humble. ``` ## Launch a fresh instance of the current Ubuntu LTS ``` -$ multipass launch ubuntu +$ multipass launch lts -Launching dancing-chipmunk... -Downloading Ubuntu 18.04 LTS.......... -Launched: dancing chipmunk +Launched: dancing-chipmunk ``` ## Check out the running instances @@ -65,10 +69,12 @@ Launched: dancing chipmunk ``` $ multipass list -Name State IPv4 Release -dancing-chipmunk RUNNING 10.125.174.247 Ubuntu 18.04 LTS -live-naiad RUNNING 10.125.174.243 Ubuntu 18.04 LTS -snapcraft-asciinema STOPPED -- Ubuntu Snapcraft builder for Core 18 +Name State IPv4 Image +dancing-chipmunk Running 192.168.64.8 Ubuntu 24.04 LTS + 10.1.23.64 Ubuntu 24.04 LTS +phlegmatic-bluebird Stopped -- Ubuntu 22.04 LTS +docker Running 192.168.64.11 Ubuntu 22.04 LTS + 172.17.0.1 ``` ## Learn more about an instance @@ -77,14 +83,16 @@ snapcraft-asciinema STOPPED -- Ubuntu Snapcraft buil $ multipass info dancing-chipmunk Name: dancing-chipmunk -State: RUNNING -IPv4: 10.125.174.247 -Release: Ubuntu 18.04.1 LTS -Image hash: 19e9853d8267 (Ubuntu 18.04 LTS) +Snapshots: 0 +IPv4: 192.168.64.8 + 10.1.23.64 +Release: Ubuntu 24.04 LTS +Image hash: e2608bfdbc44 (Ubuntu 24.04 LTS) CPU(s): 1 -Load: 0.97 0.30 0.10 -Disk usage: 1.1G out of 4.7G -Memory usage: 85.1M out of 985.4M +Load: 5.70 4.58 2.63 +Disk usage: 3.3GiB out of 4.8GiB +Memory usage: 769.0MiB out of 953.0MiB +Mounts: -- ``` ## Connect to a running instance @@ -92,7 +100,7 @@ Memory usage: 85.1M out of 985.4M ``` $ multipass shell dancing-chipmunk -Welcome to Ubuntu 18.04.1 LTS (GNU/Linux 4.15.0-42-generic x86_64) +Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.8.0-39-generic aarch64) ... ``` @@ -104,10 +112,10 @@ Don't forget to logout (or Ctrl-D) or you may find yourself heading all the way $ multipass exec dancing-chipmunk -- lsb_release -a No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 18.04.1 LTS -Release: 18.04 -Codename: bionic +Distributor ID: Ubuntu +Description: Ubuntu 24.04 LTS +Release: 24.04 +Codename: noble ``` ## Stop an instance to save resources @@ -124,11 +132,14 @@ $ multipass delete dancing-chipmunk The instance will now show up as deleted: -```$ multipass list +``` +$ multipass list -Name State IPv4 Release -snapcraft-asciinema STOPPED -- Ubuntu Snapcraft builder for Core 18 -dancing-chipmunk DELETED -- Not Available +Name State IPv4 Image +dancing-chipmunk Deleted -- Ubuntu 24.04 LTS +phlegmatic-bluebird Stopped -- Ubuntu 22.04 LTS +docker Running 192.168.64.11 Ubuntu 22.04 LTS + 172.17.0.1 ``` If you want to completely get rid of it: @@ -144,17 +155,17 @@ multipass help multipass help ``` -# Make your own build +# Start developing Multipass -Here's a set of steps to make and run your own build of Multipass. +Here's a set of steps to build the Multipass source code on Linux. -Please note that the following instructions are for building Multipass for Linux only. These instructions do not support building packages for macOS or Windows systems. +Please note that these instructions do not support building packages for macOS or Windows systems. ## Build dependencies ``` cd -apt install devscripts equivs +sudo apt install devscripts equivs mk-build-deps -s sudo -i ``` @@ -202,12 +213,7 @@ Optionally, enable auto-complete in Bash: source /completions/bash/multipass ``` -Finally, launch the Multipass clients: - -``` -/build/bin/multipass launch --name foo # CLI client -/build/bin/multipass.gui # GUI client -``` +Now you can use the `multipass` command from your terminal (for example `/build/bin/multipass launch --name foo`) or launch the GUI client with the command `/build/bin/multipass.gui`. # Contributing guidelines From 7cbc41d52924fc8bbb0db38435ed0bfa629d5026 Mon Sep 17 00:00:00 2001 From: Giulia Zanchi Date: Mon, 12 Aug 2024 15:51:07 +0200 Subject: [PATCH 3/6] Update README.md Removed secondary IP address from "dancing-chipmunk" in the first example output of `multipass list`. Signed-off-by: Giulia Zanchi --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 56254e82dd..3b59091a87 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,6 @@ $ multipass list Name State IPv4 Image dancing-chipmunk Running 192.168.64.8 Ubuntu 24.04 LTS - 10.1.23.64 Ubuntu 24.04 LTS phlegmatic-bluebird Stopped -- Ubuntu 22.04 LTS docker Running 192.168.64.11 Ubuntu 22.04 LTS 172.17.0.1 From 9abcca2108b90e62897df80ff9f17f5b1af673b6 Mon Sep 17 00:00:00 2001 From: Giulia Zanchi Date: Mon, 12 Aug 2024 15:52:38 +0200 Subject: [PATCH 4/6] Update README.md Removed secondary IP from "dancing-chipmunk" in the output of `multipass info`. Signed-off-by: Giulia Zanchi --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 3b59091a87..2f5b7ce091 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,6 @@ $ multipass info dancing-chipmunk Name: dancing-chipmunk Snapshots: 0 IPv4: 192.168.64.8 - 10.1.23.64 Release: Ubuntu 24.04 LTS Image hash: e2608bfdbc44 (Ubuntu 24.04 LTS) CPU(s): 1 From a803b4eb9dfb65eaecd3625d5302328c625215da Mon Sep 17 00:00:00 2001 From: Giulia Zanchi Date: Mon, 12 Aug 2024 15:53:50 +0200 Subject: [PATCH 5/6] Update README.md Fixed space alignment Signed-off-by: Giulia Zanchi --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2f5b7ce091..40cca90f0f 100644 --- a/README.md +++ b/README.md @@ -110,10 +110,10 @@ Don't forget to logout (or Ctrl-D) or you may find yourself heading all the way $ multipass exec dancing-chipmunk -- lsb_release -a No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 24.04 LTS -Release: 24.04 -Codename: noble +Distributor ID: Ubuntu +Description: Ubuntu 24.04 LTS +Release: 24.04 +Codename: noble ``` ## Stop an instance to save resources From 350db15c87670888b7beec1ff64bdee4f9d7b6fa Mon Sep 17 00:00:00 2001 From: Giulia Zanchi Date: Mon, 12 Aug 2024 16:33:09 +0200 Subject: [PATCH 6/6] Update README.md Co-authored-by: ScottH <59572507+sharder996@users.noreply.github.com> Signed-off-by: Giulia Zanchi --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 40cca90f0f..abc775e24f 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,7 @@ docker Running 192.168.64.11 Ubuntu 22.04 LTS $ multipass info dancing-chipmunk Name: dancing-chipmunk +State: Running Snapshots: 0 IPv4: 192.168.64.8 Release: Ubuntu 24.04 LTS