Quick Start Guide: MAAS Development


  • Ubuntu 18.04 LTS
  • A fast internet connection

More Information

This guide assumes Ubuntu is installed as your desktop environment, but it can also either be in a container, or a VM (hopefully with plenty of RAM and CPU allocated to it!).

You’ll want a fast internet connection for downloading development dependencies, downloading MAAS images to the region controller, and connecting to the Ubuntu archive (for deployments) .

Most users of MAAS will be using an Ubuntu LTS release. As developers, we need to strike a balance between using what the majority of our customers are using, and doing forward-looking work with the latest development release of Ubuntu. Therefore, (at least for beginners) the easiest way to develop MAAS is to first install the latest Ubuntu LTS release.

When backporting bug fixes to previous releases, MAAS developers will also need to have previous LTS releases available for running the unit tests, and end-to-end testing.

Required Packages

First, you will need to install basic software development and version control tools, as follows:

sudo apt install build-essential git

Next, clone the MAAS source code from Launchpad, such as the following (it doesn’t matter where you put the maas sandbox, but this guide will assume it will be in $HOME/maas):

cd $HOME
git clone https://git.launchpad.net/maas
cd maas

Once you have cloned the MAAS repository, take a look at HACKING.rst for more information on developing MAAS. (This unofficial guide only covers the basics.)

The remainder of the required packages are referenced in the MAAS source tree, and can be installed en masse as follows (assuming ~/maas is the current directory):

make install-dependencies

More information

You may be prompted for your password, in order to install all the prerequisites via sudo.

Assuming a fresh installation of Ubuntu, this will install several hundred packages on your system, including PostgreSQL, BIND, ISC dhcpd, nginx, and more. Consider developing in a container if you don’t want these to be installed directly on your development machine.

If you want to view or edit the packages that will be installed, take a look in the required-pacakges/ directory in the MAAS source tree.

Setting up the MAAS Sandbox

Getting Started

To set up your new MAAS development sandbox, simply run:

More information

This command will run the default target in the Makefile, which will do a number of things, including:

  • Download nodejs and yarn tarballs from the internet for use with MAAS development.
  • Use yarn to set up Node.js dependencies.
  • Configure a cache in ~/.buildout for Python dependencies
  • Populate the bin/ directory in the MAAS sandbox with a number of useful utility scripts for testing MAAS.

Running the Development Environment

A minimal MAAS development environment can be run directly from the MAAS sandbox. To run it, first you’ll need to prepare the MAAS database. You can do that with:

make syncdb

This will create a PostgreSQL database in the db/ directory inside your MAAS sandbox for use with the development environment. Then, you can start the development version of the MAAS server as follows:

make start

After that, you should be able to browse to http://localhost:5240/MAAS/ and log into the Web UI (replace localhost with the IP address of the MAAS server if it isn’t running on your local machine, such as in a container or VM).


You won’t have the sudo maas command available in the development environment, but you can run the equivalent:

bin/maas-region createadmin

You will be prompted for your desired username, password, and your Launchpad username (for importing your SSH keys). If you then return to your browser and enter your username and password, you will be presented with the MAAS “First User Journey” (most options here probably won’t apply, so you can use the “Skip” button in the upper right to bypass it).

Adding Sample Data

The MAAS UI is fairly boring without any machines or devices to look at. For development purposes, you can add in some fake data by running:

make sampledata

After that, browsing the MAAS UI should be a little more interesting. (Note that this also adds an admin user with the password test, so you may want to pick a username other than admin when you run bin/maas-region createadmin in order to avoid conflicts.

1 Like