- Development setup
- MAAS deployments
- Creating a Multipass instance
- Creating a LXD instance
- Creating a fake windows image
- Show intro
- Sample data
Note: You will need access to a running instance of MAAS in order to run maas-ui.
You can run MAAS-UI on your local machine assuming that you already have an instance of MAAS running somewhere that you can connect to.
In the following sections we assume that you're having your MAAS back-end running on http://10.10.0.30:5240
. This can easily be adapted to other IPs, names, or https
.
These instructions have been tested on Ubuntu 24.04 (Noble Numbat).
You need at least 5GB of free space to setup MAAS-UI (about 2.6gb of node modules and 2gb for Cypress cache).
- Go to your source folder (e.g.
mkdir $HOME/src && cd src
) git clone [email protected]:canonical/maas-ui.git
if you are using SSH- or
git clone https://github.com/canonical/maas-ui.git
if you want to clone without logging in to GitHub
- or
- Install the Node Version Manager (NVM)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
- Log out of shell and log in again
- In your
maas-ui
folder (cd maas-ui
) do- [optional if you have the correct node version]
nvm install
to install the version of node that is specified in.nvmrc
- [optional if you have
yarn
installed]npm --global install yarn
to install yarn yarn
to install dependencies- create/edit
.env.local
and setMAAS_URL="http://10.10.0.30:5240"
assuming you have a MAAS backend running on IP10.10.0.30
- Run
yarn start
to start your front-end- Make sure to use the bottom address (ending in
:8400
) to connect to MAAS-UI as this one proxies websocket connections properly to your back-end.
- Make sure to use the bottom address (ending in
- [optional if you have the correct node version]
- To run the entire unit test suite run
yarn test
- To run a sigle unit test run
yarn test path/to/test-file.jxs
- Fuzzy matching works, e.g
yarn test FormikFormButtons
finds the appropriate file to test automatically
- Fuzzy matching works, e.g
- To run Cypress end-to-end tests run
yarn cypress-open
- Click
start e2e testing
- Click the browser you'd like to use for our test
Performance tests use Sitespeed.io and are run when PRs are merged.
Sitespeed can also be run manually, though the tests expect a MAAS with a specific dataset. For best results a local MAAS can be set up using sample data.
To run against a MAAS deployment you can use:
yarn sitespeed --browsertime.domain=[maas.ip.or.hostname]
To run against a local UI you will also need to set the port:
yarn sitespeed --browsertime.domain=[maas-ui.ip.or.hostname] --browsertime.port=8400
Usually you do not have to care about manually building the bundle as our CI will do this. However, if you want to test a production version of MAAS UI just run yarn build
.
An optimised production bundle will be created in ./build
.
Make sure you've signed the Contributor agreement (CLA). If you do not sign the CLA your contributions cannot be accepted, unfortunately. Please note that our CI is going to check if you signed the CLA for the email address that you used to commit your contributions or your email belongs to a company that signed the agreement on your behalf.
To contribute, you will need to make a fork of the maas-ui project in GitHub and clone this one to your workstation. Then do the following to be able to upstream your changes:
cd maas-ui
git remote add origin [email protected]:<github-username>/maas-ui
git remote update <github-username>
git checkout -b <my-branch>
git push <mybranch>
git push <github-username> <my-branch>
Now you are ready to create a PR from GitHub by browsing to the branch that you just set up.
Important tips:
- We use conventional commits and conventional PRs and the format will be enforced by our CI. To make your life easy, you should commit using them right from the start. You can see a list of valid scopes here
- Although you can technically make a PR for contributions that you created on on the
main
branch, we encourage you to create a branch for your work and commit often. - Now all you need to do is open a PR and we will check your code. If there is nothing malicious in it we will run our CI over it, start testing and will get back to you.
Some re-usable components for MAAS reside in the maas-react-components repository. If you need or want to change any of these components you can link your local maas-react-components
- Move out of your
maas-ui
source folder:cd ..
git clone https://github.com/canonical/maas-react-components
cd maas-react-components
npm install
npm run build:watch
<-- leave this running in the background so that changes in this repository get synced to themaas-ui
repositoryyarn link
- Move back to MAAS-UI
cd ../maas-ui
yarn link "@canonical/maas-react-components"
We are also upstreaming some components for other projects. If you want or need to change those components, you will need to link this repository again. We recommend not doing this for beginners as it is unlikely that you will need to change any of those components for most of your development tasks.
- Move out of your
maas-ui
source folder:cd ..
git clone https://github.com/canonical/react-components
yarn
yarn run link-packages
yarn build-watch
- Go back to MAAS-UI
cd ../maas-ui
yarn link react
yarn link react-dom
yarn link @canonical/react-components
You may wish to use an existing instance, or you can create a Multipass instance or create a LXD instance.
For now we'll assume you have an instance called "dev".
Start your instance:
multipass start dev
Make sure your instance has SSH credentials and then SSH into your machine, optionally with agent forwarding:
ssh [-A] [email protected]
Start your instance:
lxc start dev
Connect to the instance as the provided ubuntu
user:
lxc exec dev bash -- su ubuntu
If you're planning to contribute changes to maas-ui then first you'll need to make a fork of the maas-ui project in GitHub.
Then, inside your MAAS container clone the maas-ui repository.
git clone -o upstream [email protected]:canonical/maas-ui
cd maas-ui
git remote add origin [email protected]:<github-username>/maas-ui
Otherwise you can just use:
git clone [email protected]:canonical/maas-ui
cd maas-ui
By default maas-ui will connect to maas-ui-demo.internal
which requires Canonical VPN access. maas-ui-demo.internal
runs on MAAS latest/edge, which is the latest development version available.
If you wish to develop against a different MAAS then you can create a local env:
touch .env.local
Update the contents of that file to point to a MAAS. See the section on MAAS deployments.
MAAS_URL="http://<maas-ip-or-hostname>:5240/"
The easiest way to run maas-ui is with Dotrun. You can install it with:
sudo snap install dotrun
You should now be able to run maas-ui and log into your MAAS:
dotrun
Once everything has built you can access the site using the hostname:
To run a branch from a PR you can find and click on the link "command line instructions" and copy the command from "Step 1". It should look something like:
git checkout -b username-branch-name main
git pull https://github.com/username/maas-ui.git branch-name
Run those commands from the maas-ui dir (cd ~/maas-ui
).
Then run the branch with:
dotrun
If something doesn't seem right you can try:
dotrun clean
dotrun
The easiest way to run a MAAS locally is using a snap. However, this method does not provide sample data and therefore will not have everything e.g. there will be no machines.
First you'll need to either create a Multipass instance or create a LXD container, call it something like "snap-maas".
Then enter the shell for that instance:
multipass shell snap-maas
lxc exec snap-maas -- su ubuntu
Now install MAAS and a test database:
sudo snap install maas maas-test-db
Once that has completed you'll need to intialise the MAAS:
sudo maas init region+rack --database-uri maas-test-db:///
Now create a user:
sudo maas createadmin
You should now be able to access the MAAS in your browser:
http://snap-maas.local:8400/MAAS/.
You might now need to configure maas-ui to use this MAAS.
To update your MAAS manually you can run:
sudo snap refresh maas
You can update to a different version with something like:
sudo snap refresh --channel=2.8 maas
See the MAAS Dev Setup project for a way to set up a single node development setup for MAAS easily.
If you have previously built the UI then run:
cd ~/maas
make clean-ui
Optional: if you wish to use a specific branch of maas-ui then run:
git config --file=.gitmodules submodule.src/maasui/src.url https://github.com/[github-username]/maas-ui.git
git config --file=.gitmodules submodule.src/maasui/src.branch [branch name]
git submodule sync
git submodule update --init --recursive --remote
Optional: if you want to restore to maas-ui main then run:
git checkout .gitmodules
git submodule sync
git submodule update --init --recursive --remote
Now you can make the UI
make ui
Now you need to sync your changes and restart MAAS:
cd ~/maas
make sync-dev-snap
sudo service snap.maas.supervisor restart
You should now be able to access the MAAS in your browser:
http://dev-maas.local:8400/MAAS/.
First, install Multipass:
To be able to run maas-ui or MAAS you should allocate as many resources as you can to the instance. Don't worry, it'll share the CPU and RAM with the host and only take up the disk space it currently requires.
Note: you can't increase the disk size once the instance has been created
Check what resources your computer has and then run:
multipass launch -c [the number of cores] -d [some amount of disk space] -m [the amount of ram] --name [the instance name]
You should end up with a command something like this:
multipass launch -c 4 -d 20G -m 16G --name dev
You have two options for having SSH credentials in your Multipass instance.
This method allows you to use the SSH credentials from your host machine and doesn't require you to create new SSH credentials for each Multipass instance.
You can follow this guide for setting up the ssh-agent.
Then you can log into your instance with:
ssh -A multipass@[instance-name].local
Access your instance with:
multipass shell [instance-name]
Then generate a new SSH key and add it to your Github account.
To connect to a remote MAAS over the VPN, you'll need to configure nat on your macOS host:
- run
ifconfig
and make note of theutun
interfaces. - For every
utun
interface, add the following line to/etc/pf.conf
directly after any existingnat-anchor
ornat
commands (the order is significant):
nat on utun0 from bridge100:network to any -> (utun0)
- Run
sudo pfctl -f /etc/pf.conf
to update configuration. - You should be able to
ping karura.internal
from your maas multipass.
Be aware that this may prevent reaching hosts on your internal network. You can of course comment out the nat
configuration and rerun sudo pfctl -f /etc/pf.conf
to reset everything.
The recommended way to install LXD is with the snap. For the latest stable release, use:
snap install lxd
If you previously had the LXD deb package installed, you can migrate all your existing data over with:
lxd.migrate
See the official LXD docs for information on installing LXD on other OSes.
By default, LXD comes with no configured network or storage. You can get a basic configuration suitable for MAAS with:
lxd init
You can launch an instance with the command lxc launch
:
lxc launch imageserver:imagename instancename
For example, to create an instance based on the Ubuntu Focal Fossa image with the name focal-maas
, you would run:
lxc launch ubuntu:20.04 focal-maas
See the image server for LXC and LXD for a list of available images.
Access your instance with:
lxc exec [container-name] bash -- su ubuntu
Then generate a new SSH key and add it to your Github account.
You can create a fake Windows image if you need to test MAAS with a windows image (e.g. for managing license keys).
Note: you will need a local development or snap MAAS.
Connect to you instance:
multipass shell dev-maas
lxc exec dev-maas bash -- su ubuntu
Now create a fake Windows image:
dd if=/dev/zero of=windows-dd bs=512 count=10000
You will need to log in to the CLI (if you haven't before).
You will be prompted for you API key which you can get from <your-maas-url>:5240/MAAS/r/account/prefs/api-keys
.
<path-to-maas-dir>/bin/maas login <new-profile-name> http://localhost:5240/MAAS/
maas login <new-profile-name> http://localhost:5240/MAAS/
Ensure you have downloaded and synced an amd64 ubuntu image (via <your-maas-url>:5240/MAAS/l/images
), this is required to populate architecture for the following step.
Now you can upload the image (remember to use <path-to-maas-dir>/bin/maas/...
if you're using a development MAAS):
maas <profile-name> boot-resources create name=windows/win2012 title="Windows Server 2012" architecture=amd64/generic filetype=ddtgz content@=windows-dd
Then you should be able to visit <your-maas-url>:5240/MAAS/l/images
and your Windows image should appear under the "Custom Images" section.
If you're testing license keys the format is: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
.
First you'll need to log in to the MAAS cli.
Then you reset the config to display the intro.
maas $PROFILE maas set-config name=completed_intro value=false
To use sample data with MAAS you'll first need to set up a local MAAS.
Next you'll need to get some sample data. The easiest way is to get a database dump from CI. Or alternatively you can create a dump.
Put the database dump onto your container and then run the following commands inside that container:
sudo cp path/to.dump /var/snap/maas-test-db/common/maasdb.dump
sudo snap run --shell maas-test-db.psql -c 'db-dump restore /var/snap/maas-test-db/common/maasdb.dump maassampledata'
sudo maas init region+rack --maas-url=${{env.MAAS_URL}}/MAAS --database-uri maas-test-db:///
sudo sed -i "s/database_name: maasdb/database_name: maassampledata/" /var/snap/maas/current/regiond.conf
sudo snap restart maas
Once MAAS has restarted you should be able to access the MAAS and see the data.