diff --git a/docs/conf.py b/docs/conf.py index e4d25b08e1..24971676b8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -227,7 +227,8 @@ "https://unix.stackexchange.com", # it seems stackexchange is now blocking bots "https://developer.hashicorp.com/packer", "https://www.freedesktop.org/*", - "https://asciinema.org/*" + "https://asciinema.org/*", + "https://askubuntu.com/a/4404" ] linkcheck_retries = 3 diff --git a/docs/index.md b/docs/index.md index 0b2b0a40e5..e0bc5c03f3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,7 +26,7 @@ Developers can use Multipass to prototype cloud deployments and to create fresh, Start here to install and launch your first Multipass instance. -- Tutorial: [Getting stated with Multipass](tutorial-index) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) +- Tutorial: [Getting started with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos) ### Using Multipass diff --git a/docs/tutorial/availability-zones.md b/docs/tutorial/availability-zones.md new file mode 100644 index 0000000000..13ed26d722 --- /dev/null +++ b/docs/tutorial/availability-zones.md @@ -0,0 +1,202 @@ +(tutorial-availability-zones)= +# Multipass availability zones with a load-balanced web service + +In this tutorial, we will use Multipass availability zones to build a simple, highly available web service. We will deploy three Nginx web servers, one in each availability zone, and a fourth instance acting as a load balancer to distribute traffic between them. + +In the real world, availability zones are clusters of data centers in a particular region. Multipass provides a local simulation of availability zones for development purposes. + +To complete this tutorial, you need Multipass 1.17 or later installed on your host. + +## Check the available zones + +Multipass ships with a fixed set of availability zones. List them, along with their status, before you start: + +```bash +multipass zones +``` + +Sample output: + +```text +Name State Subnet +zone1 Available 192.168.252.0/24 +zone2 Available 192.168.253.0/24 +zone3 Available 192.168.254.0/24 +``` + +```{note} +Multipass assigns each zone its own subnet, simulating the network separation between real-world availability zones. +``` + +We will spread our web servers across `zone1`, `zone2` and `zone3`. + +## Launch the web servers + +First, let's launch one web server in each availability zone. We will customize their landing pages so we can easily see which zone is responding. + +### Launch and configure the first server (zone1) + +```bash +multipass launch --name web-a --zone zone1 +multipass exec web-a -- sudo apt-get update +multipass exec web-a -- sudo apt-get install -y nginx +multipass exec web-a -- bash -c 'echo "

Welcome to web-a in zone1

" | sudo tee /var/www/html/index.html' +``` + +### Launch and configure the second server (zone2) + +```bash +multipass launch --name web-b --zone zone2 +multipass exec web-b -- sudo apt-get update +multipass exec web-b -- sudo apt-get install -y nginx +multipass exec web-b -- bash -c 'echo "

Welcome to web-b in zone2

" | sudo tee /var/www/html/index.html' +``` + +### Launch and configure the third server (zone3) + +```bash +multipass launch --name web-c --zone zone3 +multipass exec web-c -- sudo apt-get update +multipass exec web-c -- sudo apt-get install -y nginx +multipass exec web-c -- bash -c 'echo "

Welcome to web-c in zone3

" | sudo tee /var/www/html/index.html' +``` + +## Launch the load balancer + +Now we will launch a fourth instance to act as a load balancer. We will place it explicitly in `zone3` so we know exactly where it lives, and use HAProxy, a popular open-source load balancer, to distribute traffic across all three zones. + +```bash +multipass launch --name load-balancer --zone zone3 +multipass exec load-balancer -- sudo apt-get update +multipass exec load-balancer -- sudo apt-get install -y haproxy +``` + +### Configure HAProxy + +The load balancer needs the IP address of each web server so it can send incoming requests to them. Get these addresses: + +```bash +WEB_A_IP=$(multipass info web-a --format csv | awk -F, 'NR>1 {print $5}') +WEB_B_IP=$(multipass info web-b --format csv | awk -F, 'NR>1 {print $5}') +WEB_C_IP=$(multipass info web-c --format csv | awk -F, 'NR>1 {print $5}') +``` + +Create a configuration file locally and transfer it to the load balancer: + +```bash +cat << EOF > haproxy.cfg + +frontend http_front + bind *:80 + default_backend http_back + +backend http_back + balance roundrobin + server web-a $WEB_A_IP:80 check + server web-b $WEB_B_IP:80 check + server web-c $WEB_C_IP:80 check +EOF + +multipass transfer haproxy.cfg load-balancer: +multipass exec load-balancer -- sudo mv /home/ubuntu/haproxy.cfg /etc/haproxy/haproxy.cfg +multipass exec load-balancer -- sudo systemctl restart haproxy +``` + +## Test the high availability + +Find the IP address of your load balancer: + +```bash +LB_IP=$(multipass info load-balancer --format csv | awk -F, 'NR>1 {print $5}') +``` + +From now on, send requests only to the load balancer. It decides which healthy backend server responds. Query it once: + +```bash +curl http://$LB_IP +``` + +*Expected output:* + +```text +

Welcome to web-a in zone1

+``` + +Run the command again: + +```bash +curl http://$LB_IP +``` + +This time, the response comes from the next web server in another availability zone: + +```text +

Welcome to web-b in zone2

+``` + +### Simulate a zone failure + +To simulate an outage of an entire availability zone, disable `zone1`. Multipass forcefully switches off every instance in that zone and keeps them off until the zone is re-enabled, mirroring a real cloud provider losing a zone: + +```bash +multipass disable-zones zone1 +``` + +After a few moments, query the same load balancer address twice. HAProxy detects that `web-a` is unavailable and sends the requests to the surviving web servers: + +```bash +curl http://$LB_IP +curl http://$LB_IP +``` + +*Expected output (the order may vary):* + +```text +

Welcome to web-b in zone2

+

Welcome to web-c in zone3

+``` + +Notice that none of the responses comes from `web-a` in `zone1`. + +### Take down a second zone + +Now disable `zone2` as well, leaving only `zone3` healthy: + +```bash +multipass disable-zones zone2 +``` + +Query the load balancer again. With two zones down, every request can only come from `web-c` in `zone3`: + +```bash +curl http://$LB_IP +``` + +*Expected output:* + +```text +

Welcome to web-c in zone3

+``` + +## Tear down the environment + +### Restore the zones + +Bring both zones back online. Instances that were running when the zones were disabled are started again automatically: + +```bash +multipass enable-zones zone1 zone2 +``` + +After a few moments, `web-a` and `web-b` rejoin the rotation and the load balancer serves all three zones once more. + +Let's now delete the instances, free their resources on our host machine, and remove the local HAProxy configuration file: + +```bash +multipass delete --purge web-a web-b web-c load-balancer +rm haproxy.cfg +``` + +## Summary + +You have built a highly available web service that spans all three availability zones. Even when an entire zone goes offline, your users can still access the application through the healthy zones, demonstrating the power of infrastructure redundancy with Multipass. diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md new file mode 100644 index 0000000000..17156a26f0 --- /dev/null +++ b/docs/tutorial/getting-started.md @@ -0,0 +1,629 @@ +(tutorial-getting-started)= +# Getting started with Multipass + + + +Multipass is a flexible and powerful tool that can be used for many purposes. In its simplest form, you can use it to quickly create and destroy Ubuntu VMs (instances) on any host machine. But you can also use Multipass to build a local mini-cloud on your laptop, to test and develop multi-instance or container-based cloud applications. + +This tutorial will help you understand how Multipass works, and the skills you need to use its main features. + +## Install Multipass + +Multipass is available for Linux, macOS and Windows. To install it on the OS of your choice, please follow the instructions provided in [How to install Multipass](/how-to-guides/install-multipass). + +```{note} +Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. +``` + +## Create and use a basic instance + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +Start Multipass from the application launcher. In Ubuntu, press the super key and type "Multipass", or find Multipass in the Applications panel on the lower left of the desktop. + +```{figure} /images/tutorial/mp-linux-1.png + :width: 800px + :alt: Find Multipass in the Applications panel +``` + + + +After launching the application, you should see the Multipass tray icon on the upper right section of the screen. + +```{figure} /images/tutorial/mp-linux-2.png + :width: 688px + :alt: Multipass tray icon +``` + + + +Click on the Multipass icon and select **Open Shell**. + +```{figure} /images/tutorial/mp-linux-2a.png + :width: 286px + :alt: Multipass tray icon - Select "Open shell" +``` + + + +Clicking this button does many things in the background: +* It creates a new virtual machine (instance) named `primary`, with 1GB of RAM, 5GB of disk, and 1 CPU. See also: {ref}`primary-instance` +* It installs the most recent Ubuntu LTS release on that instance. +* It mounts your `$HOME` directory in the instance. +* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. + + + +```{caution} +If your local home folder is encrypted using `fscrypt` and you are having trouble accessing its contents when it is automatically mounted inside your primary instance, see [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder). +``` + +You can see elements of this in the printout below: + +```{code-block} text +Launched: primary +Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) + + * Documentation: https://docs.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/pro + + System information as of Tue Jun 9 15:54:32 UTC 2026 + + System load: 0.4 Processes: 123 + Usage of /: 67.7% of 3.70GB Users logged in: 0 + Memory usage: 29% IPv4 address for eth0: 10.97.0.49 + Swap usage: 0% + + +Expanded Security Maintenance for Applications is not enabled. + +0 updates can be applied immediately. + +Enable ESM Apps to receive additional future security updates. +See https://ubuntu.com/esm or run: sudo pro status + +ubuntu@primary:~$ +``` + +Let's test it. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory: + +```{figure} /images/tutorial/mp-linux-3.png + :width: 720px + :alt: Create new "Multipass_Files" folder +``` + + + +As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: + +```{code-block} text +cd ./Home/Multipass_Files/ +cat README.md +``` + +Sample output: + +```{code-block} text +## Shared Folder + +This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! +``` + +```` + +````{tab-item} macOS +:sync: macOS + +Start Multipass from the application launcher. In macOS, open the application launcher, type "Multipass", and launch the application. + +```{figure} /images/tutorial/mp-macos-1.png + :width: 720px + :alt: Launch the Multipass application +``` + + + +After launching the application, you should see the Multipass tray icon in the upper right section of the screen. + +```{figure} /images/tutorial/mp-macos-2.png + :width: 684px + :alt: Multipass tray icon +``` + + + +Click on the Multipass icon and select **Open Shell**. + +```{figure} /images/tutorial/mp-macos-3.png + :width: 304px + :alt: Multipass tray icon - Select "Open shell" +``` + + + +Clicking this button does many things in the background: + +* It creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. +* It installs the most recent Ubuntu LTS release on that instance. +* It mounts your `$HOME` directory in the instance. +* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. + +You can see elements of this in the printout below: + +```{code-block} text +Launched: primary +Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) + + * Documentation: https://docs.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/pro + + System information as of Tue Jun 9 15:54:32 UTC 2026 + + System load: 0.4 Processes: 123 + Usage of /: 67.7% of 3.70GB Users logged in: 0 + Memory usage: 29% IPv4 address for eth0: 10.97.0.49 + Swap usage: 0% + + +Expanded Security Maintenance for Applications is not enabled. + +0 updates can be applied immediately. + +Enable ESM Apps to receive additional future security updates. +See https://ubuntu.com/esm or run: sudo pro status + +ubuntu@primary:~$ +``` + +Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory. + +```{figure} /images/tutorial/mp-macos-4.png + :width: 720px + :alt: Create new "Multipass_Files" folder +``` + + + +As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: + +```{code-block} text +ubuntu@primary:~$ cd ./Home/Multipass_Files/ +ubuntu@primary:~/Home/Multipass_Files$ cat README.md +## Shared Folder + +This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! + +ubuntu@primary:~/Home/Multipass_Files$ +``` + +```` + +````{tab-item} Windows +:sync: Windows + +Start Multipass from the application launcher. Press the Windows key and type "Multipass", then launch the application. + +```{figure} /images/tutorial/mp-windows-1.png + :width: 720px + :alt: Launch the Multipass application +``` + + + +After launching the application, you should see the Multipass tray icon in the lower right section of the screen (you may need to click on the small arrow located there). + +```{figure} /images/tutorial/mp-windows-2.png + :width: 429px + :alt: Multipass tray icon +``` + + + +Click on the Multipass icon and select **Open Shell**. + +```{figure} /images/tutorial/mp-windows-3.png + :width: 423px + :alt: Multipass tray icon - Select "Open shell" +``` + + + +Clicking this button does many things in the background: +* First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. +* Then, it installs the most recent Ubuntu LTS release on that instance. +* Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`. + +You can see elements of this in the printout below: + +```{code-block} text +Launched: primary +Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) + + * Documentation: https://docs.ubuntu.com + * Management: https://landscape.canonical.com + * Support: https://ubuntu.com/pro + + System information as of Tue Jun 9 15:54:32 UTC 2026 + + System load: 0.4 Processes: 123 + Usage of /: 67.7% of 3.70GB Users logged in: 0 + Memory usage: 29% IPv4 address for eth0: 10.97.0.49 + Swap usage: 0% + + +Expanded Security Maintenance for Applications is not enabled. + +0 updates can be applied immediately. + +Enable ESM Apps to receive additional future security updates. +See https://ubuntu.com/esm or run: sudo pro status + +ubuntu@primary:~$ +``` + +Try out a few Linux commands to see what you’re working with. + +```{code-block} text +ubuntu@primary:~$ free + total used free shared buff/cache available +Mem: 925804 203872 362484 916 359448 582120 +Swap: 0 0 0 +ubuntu@primary:~$ df +Filesystem 1K-blocks Used Available Use% Mounted on +tmpfs 92584 912 91672 1% /run +/dev/sda1 4893836 1477300 3400152 31% / +tmpfs 462900 0 462900 0% /dev/shm +tmpfs 5120 0 5120 0% /run/lock +/dev/sda15 106858 5329 101529 5% /boot/efi +tmpfs 92580 4 92576 1% /run/user/1000 +``` + +```` + +````` + +Congratulations, you've got your first instance! + +This instance is great for when you just need a quick Ubuntu VM, but let's say you want a more customised instance, how can you do that? Multipass has you covered there too. + +```{dropdown} Optional Exercises + +Exercise 1: +When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first). + +Exercise 2: +In Multipass, an instance with the name "primary" is privileged. That is, it serves as the default argument of `multipass shell` among other capabilities. In different terminal instances, check `multipass shell primary` and `multipass shell`. Both commands should give the same result. +``` + +## Create a customised instance + +Multipass has a great feature to help you get started with creating customised instances. Open a terminal and run the `multipass find` command. The result shows a list of all images you can currently launch through Multipass. + +```{code-block} text +$ multipass find +Image Aliases Version Description +22.04 jammy 20260515 Ubuntu 22.04 LTS +24.04 noble 20260518 Ubuntu 24.04 LTS +25.10 questing 20260520 Ubuntu 25.10 +26.04 resolute,lts,ubuntu 20260520 Ubuntu 26.04 LTS +core:core16 current Ubuntu Core 16 +core:core18 current Ubuntu Core 18 +core:core20 current Ubuntu Core 20 +core:core22 current Ubuntu Core 22 +core:core24 current Ubuntu Core 24 +core:core26 current Ubuntu Core 26 +debian trixie 20260601 Debian Trixie +fedora 20260422 Fedora 44 +``` + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: + +```{code-block} text +$ multipass launch resolute +Launched: coherent-trumpetfish +``` + +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". + +You can check some basic info about your new instance by running the following command: + +```{code-block} text +$ multipass exec coherent-trumpetfish -- lsb_release -a +No LSB modules are available. +Distributor ID: Ubuntu +Description: Ubuntu 26.04 LTS +Release: 26.04 +Codename: resolute +``` + +This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. + +Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: + +`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` + +You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. + +```{code-block} text +$ multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 10.110.66.139 +Release: Ubuntu 26.04 LTS +Image hash: dced94c031cc (Ubuntu 26.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + +```` + +````{tab-item} macOS +:sync: macOS + +Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: + +```{code-block} text +$ multipass launch resolute +Launched: coherent-trumpetfish +``` + +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". + +You can check some basic info about your new instance by running the following command: + +```{code-block} text +$ multipass exec coherent-trumpetfish -- lsb_release -a +No LSB modules are available. +Distributor ID: Ubuntu +Description: Ubuntu 26.04 LTS +Release: 26.04 +Codename: resolute +``` + +This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. + +Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: + +`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` + +You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. + +```{code-block} text +$ multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 10.110.66.139 +Release: Ubuntu 26.04 LTS +Image hash: dced94c031cc (Ubuntu 26.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + +```` + +````{tab-item} Windows +:sync: Windows + +Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: + +```{code-block} text +C:\WINDOWS\system32> multipass launch resolute +Launched: coherent-trumpetfish +``` + +Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". + +You can check some basic info about your new instance by running the following command: + +```{code-block} text +C:\WINDOWS\system32> multipass exec coherent-trumpetfish -- lsb_release -a +No LSB modules are available. +Distributor ID: Ubuntu +Description: Ubuntu 26.04 LTS +Release: 26.04 +Codename: resolute +``` + +This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. + +Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: + +`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` + +You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. + +```{code-block} text +C:\WINDOWS\system32> multipass info ltsInstance +Name: ltsInstance +State: Running +IPv4: 10.110.66.139 +Release: Ubuntu 26.04 LTS +Image hash: dced94c031cc (Ubuntu 26.04 LTS) +CPU(s): 2 +Load: 1.11 0.36 0.12 +Disk usage: 1.4GiB out of 9.5GiB +Memory usage: 170.4MiB out of 1.9GiB +Mounts: -- +``` + +```` + +````` + +## Manage instances + +Perhaps after using the "coherent-trumpetfish" instance for a while, you decide to delete it by running the following command: + +`multipass delete coherent-trumpetfish` + + +`````{tab-set} + +````{tab-item} Linux +:sync: Linux + +You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 26.04 LTS +coherent-trumpetfish Deleted -- Not Available +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS +``` + +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 26.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS +``` + +```` + +````{tab-item} macOS +:sync: macOS + +You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 26.04 LTS +coherent-trumpetfish Deleted -- Not Available +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS +``` + +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. + +```{code-block} text +$ multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 26.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS +``` + +```` + +````{tab-item} Windows +:sync: Windows + +You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. + +```{code-block} text +C:\WINDOWS\system32> multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 26.04 LTS +coherent-trumpetfish Deleted -- Not Available +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS +``` + +The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. + +```{code-block} text +C:\WINDOWS\system32> multipass list +Name State IPv4 Image +primary Running 10.110.66.242 Ubuntu 26.04 LTS +ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS +``` + +```` + +````` + +You've now seen a few ways to create, customise, and delete an instance. It is time to put those instances to work! + +## Put your instances to use: Run a simple web server + +Let's see a practical example of what you can do with your Multipass instances. One way to put a Multipass instance to use is by running a local web server in it. + +Return to your customised LTS instance. Take note of its IP address, which was revealed when you ran `multipass list`. Then run `multipass shell ltsInstance` to open a shell in the instance. + +From the shell, you can run: + +```{code-block} text +sudo apt update + +sudo apt install apache2 +``` + +Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage. + + + +```{figure} /images/tutorial/mp-apache.png + :width: 720px + :alt: Default Apache homepage +``` + + + + +Just like that, you've got a web server running in a Multipass instance! + +You can use this web server locally for any kind of local development or testing. However, if you want to access this web server from the internet (for instance, a different computer), you need an instance that is exposed to the external network. + +## Next steps + +Congratulations! You can now use Multipass proficiently. + +There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/index) for ideas and help with your project. In our [Explanation](/explanation/index) and [Reference](/reference/index) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more. + +Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/project/multipass/21/) and let us know what you are doing with your instances! + + + + diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 9a697635f1..60665336fa 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,629 +1,22 @@ (tutorial-index)= # Tutorial - +These tutorials provide guided, hands-on introductions to Multipass: -Multipass is a flexible and powerful tool that can be used for many purposes. In its simplest form, you can use it to quickly create and destroy Ubuntu VMs (instances) on any host machine. But you can also use Multipass to build a local mini-cloud on your laptop, to test and develop multi-instance or container-based cloud applications. +## [Getting started with Multipass](getting-started) -This tutorial will help you understand how Multipass works, and the skills you need to use its main features. +Create and configure your first Multipass instances while becoming familiar with the main features and commands. -## Install Multipass +## [Multipass availability zones with a load-balanced web service](availability-zones) -Multipass is available for Linux, macOS and Windows. To install it on the OS of your choice, please follow the instructions provided in [How to install Multipass](/how-to-guides/install-multipass). - -```{note} -Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu. -``` - -## Create and use a basic instance - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -Start Multipass from the application launcher. In Ubuntu, press the super key and type "Multipass", or find Multipass in the Applications panel on the lower left of the desktop. - -```{figure} /images/tutorial/mp-linux-1.png - :width: 800px - :alt: Find Multipass in the Applications panel -``` - - - -After launching the application, you should see the Multipass tray icon on the upper right section of the screen. - -```{figure} /images/tutorial/mp-linux-2.png - :width: 688px - :alt: Multipass tray icon -``` - - - -Click on the Multipass icon and select **Open Shell**. - -```{figure} /images/tutorial/mp-linux-2a.png - :width: 286px - :alt: Multipass tray icon - Select "Open shell" -``` - - - -Clicking this button does many things in the background: -* It creates a new virtual machine (instance) named `primary`, with 1GB of RAM, 5GB of disk, and 1 CPU. See also: {ref}`primary-instance` -* It installs the most recent Ubuntu LTS release on that instance. -* It mounts your `$HOME` directory in the instance. -* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. - - - -```{caution} -If your local home folder is encrypted using `fscrypt` and you are having trouble accessing its contents when it is automatically mounted inside your primary instance, see [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder). -``` - -You can see elements of this in the printout below: - -```{code-block} text -Launched: primary -Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - - * Documentation: https://docs.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/pro - - System information as of Tue Jun 9 15:54:32 UTC 2026 - - System load: 0.4 Processes: 123 - Usage of /: 67.7% of 3.70GB Users logged in: 0 - Memory usage: 29% IPv4 address for eth0: 10.97.0.49 - Swap usage: 0% - - -Expanded Security Maintenance for Applications is not enabled. - -0 updates can be applied immediately. - -Enable ESM Apps to receive additional future security updates. -See https://ubuntu.com/esm or run: sudo pro status - -ubuntu@primary:~$ -``` - -Let's test it. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory: - -```{figure} /images/tutorial/mp-linux-3.png - :width: 720px - :alt: Create new "Multipass_Files" folder -``` - - - -As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: - -```{code-block} text -cd ./Home/Multipass_Files/ -cat README.md -``` - -Sample output: - -```{code-block} text -## Shared Folder - -This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! -``` - -```` - -````{tab-item} macOS -:sync: macOS - -Start Multipass from the application launcher. In macOS, open the application launcher, type "Multipass", and launch the application. - -```{figure} /images/tutorial/mp-macos-1.png - :width: 720px - :alt: Launch the Multipass application -``` - - - -After launching the application, you should see the Multipass tray icon in the upper right section of the screen. - -```{figure} /images/tutorial/mp-macos-2.png - :width: 684px - :alt: Multipass tray icon -``` - - - -Click on the Multipass icon and select **Open Shell**. - -```{figure} /images/tutorial/mp-macos-3.png - :width: 304px - :alt: Multipass tray icon - Select "Open shell" -``` - - - -Clicking this button does many things in the background: - -* It creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. -* It installs the most recent Ubuntu LTS release on that instance. -* It mounts your `$HOME` directory in the instance. -* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`. - -You can see elements of this in the printout below: - -```{code-block} text -Launched: primary -Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - - * Documentation: https://docs.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/pro - - System information as of Tue Jun 9 15:54:32 UTC 2026 - - System load: 0.4 Processes: 123 - Usage of /: 67.7% of 3.70GB Users logged in: 0 - Memory usage: 29% IPv4 address for eth0: 10.97.0.49 - Swap usage: 0% - - -Expanded Security Maintenance for Applications is not enabled. - -0 updates can be applied immediately. - -Enable ESM Apps to receive additional future security updates. -See https://ubuntu.com/esm or run: sudo pro status - -ubuntu@primary:~$ -``` - -Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory. - -```{figure} /images/tutorial/mp-macos-4.png - :width: 720px - :alt: Create new "Multipass_Files" folder -``` - - - -As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance: - -```{code-block} text -ubuntu@primary:~$ cd ./Home/Multipass_Files/ -ubuntu@primary:~/Home/Multipass_Files$ cat README.md -## Shared Folder - -This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM! - -ubuntu@primary:~/Home/Multipass_Files$ -``` - -```` - -````{tab-item} Windows -:sync: Windows - -Start Multipass from the application launcher. Press the Windows key and type "Multipass", then launch the application. - -```{figure} /images/tutorial/mp-windows-1.png - :width: 720px - :alt: Launch the Multipass application -``` - - - -After launching the application, you should see the Multipass tray icon in the lower right section of the screen (you may need to click on the small arrow located there). - -```{figure} /images/tutorial/mp-windows-2.png - :width: 429px - :alt: Multipass tray icon -``` - - - -Click on the Multipass icon and select **Open Shell**. - -```{figure} /images/tutorial/mp-windows-3.png - :width: 423px - :alt: Multipass tray icon - Select "Open shell" -``` - - - -Clicking this button does many things in the background: -* First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. -* Then, it installs the most recent Ubuntu LTS release on that instance. -* Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`. - -You can see elements of this in the printout below: - -```{code-block} text -Launched: primary -Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-15-generic x86_64) - - * Documentation: https://docs.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/pro - - System information as of Tue Jun 9 15:54:32 UTC 2026 - - System load: 0.4 Processes: 123 - Usage of /: 67.7% of 3.70GB Users logged in: 0 - Memory usage: 29% IPv4 address for eth0: 10.97.0.49 - Swap usage: 0% - - -Expanded Security Maintenance for Applications is not enabled. - -0 updates can be applied immediately. - -Enable ESM Apps to receive additional future security updates. -See https://ubuntu.com/esm or run: sudo pro status - -ubuntu@primary:~$ -``` - -Try out a few Linux commands to see what you’re working with. - -```{code-block} text -ubuntu@primary:~$ free - total used free shared buff/cache available -Mem: 925804 203872 362484 916 359448 582120 -Swap: 0 0 0 -ubuntu@primary:~$ df -Filesystem 1K-blocks Used Available Use% Mounted on -tmpfs 92584 912 91672 1% /run -/dev/sda1 4893836 1477300 3400152 31% / -tmpfs 462900 0 462900 0% /dev/shm -tmpfs 5120 0 5120 0% /run/lock -/dev/sda15 106858 5329 101529 5% /boot/efi -tmpfs 92580 4 92576 1% /run/user/1000 -``` - -```` - -````` - -Congratulations, you've got your first instance! - -This instance is great for when you just need a quick Ubuntu VM, but let's say you want a more customised instance, how can you do that? Multipass has you covered there too. - -```{dropdown} Optional Exercises - -Exercise 1: -When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first). - -Exercise 2: -In Multipass, an instance with the name "primary" is privileged. That is, it serves as the default argument of `multipass shell` among other capabilities. In different terminal instances, check `multipass shell primary` and `multipass shell`. Both commands should give the same result. -``` - -## Create a customised instance - -Multipass has a great feature to help you get started with creating customised instances. Open a terminal and run the `multipass find` command. The result shows a list of all images you can currently launch through Multipass. - -```{code-block} text -$ multipass find -Image Aliases Version Description -22.04 jammy 20260515 Ubuntu 22.04 LTS -24.04 noble 20260518 Ubuntu 24.04 LTS -25.10 questing 20260520 Ubuntu 25.10 -26.04 resolute,lts,ubuntu 20260520 Ubuntu 26.04 LTS -core:core16 current Ubuntu Core 16 -core:core18 current Ubuntu Core 18 -core:core20 current Ubuntu Core 20 -core:core22 current Ubuntu Core 22 -core:core24 current Ubuntu Core 24 -core:core26 current Ubuntu Core 26 -debian trixie 20260601 Debian Trixie -fedora 20260422 Fedora 44 -``` - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: - -```{code-block} text -$ multipass launch resolute -Launched: coherent-trumpetfish -``` - -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". - -You can check some basic info about your new instance by running the following command: - -```{code-block} text -$ multipass exec coherent-trumpetfish -- lsb_release -a -No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 26.04 LTS -Release: 26.04 -Codename: resolute -``` - -This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. - -Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: - -`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` - -You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. - -```{code-block} text -$ multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 10.110.66.139 -Release: Ubuntu 26.04 LTS -Image hash: dced94c031cc (Ubuntu 26.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -```` - -````{tab-item} macOS -:sync: macOS - -Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: - -```{code-block} text -$ multipass launch resolute -Launched: coherent-trumpetfish -``` - -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". - -You can check some basic info about your new instance by running the following command: - -```{code-block} text -$ multipass exec coherent-trumpetfish -- lsb_release -a -No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 26.04 LTS -Release: 26.04 -Codename: resolute -``` - -This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. - -Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: - -`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` - -You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. - -```{code-block} text -$ multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 10.110.66.139 -Release: Ubuntu 26.04 LTS -Image hash: dced94c031cc (Ubuntu 26.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -```` - -````{tab-item} Windows -:sync: Windows - -Launch an instance running Ubuntu 26.04 ("Resolute Raccoon") by typing the `multipass launch resolute` command: - -```{code-block} text -C:\WINDOWS\system32> multipass launch resolute -Launched: coherent-trumpetfish -``` - -Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish". - -You can check some basic info about your new instance by running the following command: - -```{code-block} text -C:\WINDOWS\system32> multipass exec coherent-trumpetfish -- lsb_release -a -No LSB modules are available. -Distributor ID: Ubuntu -Description: Ubuntu 26.04 LTS -Release: 26.04 -Codename: resolute -``` - -This tells Multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance. - -Now, launch another instance, setting its name and specific memory, disk, and CPUs by running this command: - -`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2` - -You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`. - -```{code-block} text -C:\WINDOWS\system32> multipass info ltsInstance -Name: ltsInstance -State: Running -IPv4: 10.110.66.139 -Release: Ubuntu 26.04 LTS -Image hash: dced94c031cc (Ubuntu 26.04 LTS) -CPU(s): 2 -Load: 1.11 0.36 0.12 -Disk usage: 1.4GiB out of 9.5GiB -Memory usage: 170.4MiB out of 1.9GiB -Mounts: -- -``` - -```` - -````` - -## Manage instances - -Perhaps after using the "coherent-trumpetfish" instance for a while, you decide to delete it by running the following command: - -`multipass delete coherent-trumpetfish` - - -`````{tab-set} - -````{tab-item} Linux -:sync: Linux - -You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -```` - -````{tab-item} macOS -:sync: macOS - -You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. - -```{code-block} text -$ multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -```` - -````{tab-item} Windows -:sync: Windows - -You have created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have. - -```{code-block} text -C:\WINDOWS\system32> multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -coherent-trumpetfish Deleted -- Not Available -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted. - -```{code-block} text -C:\WINDOWS\system32> multipass list -Name State IPv4 Image -primary Running 10.110.66.242 Ubuntu 26.04 LTS -ltsInstance Running 10.110.66.139 Ubuntu 26.04 LTS -``` - -```` - -````` - -You've now seen a few ways to create, customise, and delete an instance. It is time to put those instances to work! - -## Put your instances to use: Run a simple web server - -Let's see a practical example of what you can do with your Multipass instances. One way to put a Multipass instance to use is by running a local web server in it. - -Return to your customised LTS instance. Take note of its IP address, which was revealed when you ran `multipass list`. Then run `multipass shell ltsInstance` to open a shell in the instance. - -From the shell, you can run: - -```{code-block} text -sudo apt update - -sudo apt install apache2 -``` - -Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage. - - - -```{figure} /images/tutorial/mp-apache.png - :width: 720px - :alt: Default Apache homepage -``` - - - - -Just like that, you've got a web server running in a Multipass instance! - -You can use this web server locally for any kind of local development or testing. However, if you want to access this web server from the internet (for instance, a different computer), you need an instance that is exposed to the external network. - -## Next steps - -Congratulations! You can now use Multipass proficiently. - -There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/index) for ideas and help with your project. In our [Explanation](/explanation/index) and [Reference](/reference/index) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more. - -Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/project/multipass/21/) and let us know what you are doing with your instances! - - - -