Skip to content

Latest commit

 

History

History
593 lines (392 loc) · 19.1 KB

HACKING.md

File metadata and controls

593 lines (392 loc) · 19.1 KB
Raw

Hacking

Development setup

Note: You will need access to a running instance of MAAS in order to run maas-ui.

Run MAAS-UI on your local machine

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.

Setup MAAS-UI, node and yarn

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
  • 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 set MAAS_URL="http://10.10.0.30:5240" assuming you have a MAAS backend running on IP 10.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.

How to run tests

Unit tests

  • 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

Integration tests

  • 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

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

How to build the bundle

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.

How to contribute

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.

Setup MAAS React Components

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 the maas-ui repository
  • yarn link
  • Move back to MAAS-UI cd ../maas-ui
  • yarn link "@canonical/maas-react-components"

Setup Canonical 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-UIcd ../maas-ui
  • yarn link react
  • yarn link react-dom
  • yarn link @canonical/react-components

Set up a development container

Start the instance

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".

Multipass

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]

LXD

Start your instance:

lxc start dev

Connect to the instance as the provided ubuntu user:

lxc exec dev bash -- su ubuntu

Clone the repository

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

Edit local config

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:

http://dev.local:8400/MAAS/.

Running a branch

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

MAAS deployments

Snap deployment

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

multipass shell snap-maas

LXD

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.

Updating a snap 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

Development deployment

See the MAAS Dev Setup project for a way to set up a single node development setup for MAAS easily.

Running maas-ui from a development maas

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/.

Creating a Multipass instance

Install Multipass

First, install Multipass:

Create the instance:

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

SSH credentials

You have two options for having SSH credentials in your Multipass instance.

Host credentials

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

Instance credentials

Access your instance with:

multipass shell [instance-name]

Then generate a new SSH key and add it to your Github account.

macOS

VPN configuration

To connect to a remote MAAS over the VPN, you'll need to configure nat on your macOS host:

  1. run ifconfig and make note of the utun interfaces.
  2. For every utun interface, add the following line to /etc/pf.conf directly after any existing nat-anchor or nat commands (the order is significant):
nat on utun0 from bridge100:network to any -> (utun0)
  1. Run sudo pfctl -f /etc/pf.conf to update configuration.
  2. 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.

Creating a LXD instance

Install LXD on Linux

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.

Initialise LXD

By default, LXD comes with no configured network or storage. You can get a basic configuration suitable for MAAS with:

lxd init

Launch the instance

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.

Container credentials

Access your instance with:

lxc exec [container-name] bash -- su ubuntu

Then generate a new SSH key and add it to your Github account.

Creating a fake windows image

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

multipass shell dev-maas

LXD

lxc exec dev-maas bash -- su ubuntu

Create the image

Now create a fake Windows image:

dd if=/dev/zero of=windows-dd bs=512 count=10000

Login to MAAS

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.

Development MAAS

<path-to-maas-dir>/bin/maas login <new-profile-name> http://localhost:5240/MAAS/

Snap MAAS

maas login <new-profile-name> http://localhost:5240/MAAS/

Upload the image

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.

License keys

If you're testing license keys the format is: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX.

Show intro

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

Sample data

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.