Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #3629

Closed
wants to merge 2 commits into from
Closed

Update README.md #3629

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
42330a2
Update README.md
giuliazanchi Aug 8, 2024
6bce7d8
Update README.md
giuliazanchi Aug 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 80 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,46 @@
# 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 |
|-----|:---|
| [CI](https://github.com/canonical/multipass/actions) | [![Build Status][gha-image]][gha-url] |
| [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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -104,48 +111,54 @@ 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 <command>
```

# 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 <multipass>
apt install devscripts equivs
mk-build-deps -s sudo -i
```

## Building
## Build Multipass

```
cd <multipass>
Expand All @@ -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 `<multipass>` 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 `<multipass>` 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
Expand All @@ -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 <multipass>/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 <multipass>/data/multipass.gui.autostart.desktop ~/.local/share/multipass/
```

Optionally, enable auto-complete in bash:
Optionally, enable auto-complete in Bash:

```
source <multipass>/completions/bash/multipass
```

Finally, use multipass's clients:
Finally, launch the Multipass clients:

```
<multipass>/build/bin/multipass launch --name foo # CLI client
<multipass>/build/bin/multipass.gui # GUI client
<multipass>/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
Expand Down
Loading