.. -*- mode: rst -*-

 
Installing MAAS
===============

There are two main ways to install MAAS

 * :ref:`From Ubuntu's package archive on an existing Ubuntu install. <pkg-install>`
 * :ref:`As a fresh install from Ubuntu Server install media. <disc-install>`
 

If you are interested in testing the latest development version you can 
also check out the very latest source and build MAAS yourself. 


.. _pkg-install:

Installing MAAS from the archive
--------------------------------

Installing MAAS from packages is thankfully straightforward. There are
actually several packages that go into making up a working MAAS install,
but for convenience, many of these have been gathered into a virtual package
called 'maas' which will install the necessary components for a 'seed cloud',
that is a single server that will directly control a group of nodes. The main packages are:

 * ``maas`` - seed cloud setup, which includes both the region controller and
the cluster controller below.
 * ``maas-region-controller`` - includes the web UI, API and database.
 * ``maas-cluster-controller`` - controls a group ("cluster") of nodes including DHCP management.
 * ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns.

If you need to separate these services or want to deploy an additional cluster
controller, you should install the corresponding packages individually
(see :ref:`the description of a typical setup <setup>` for more background
on how a typical hardware setup might be arranged).

There are two suggested additional packages 'maas-dhcp' and 'maas-dns'. These
set up MAAS-controlled DHCP and DNS services which greatly simplify deployment
if you are running a typical setup where the MAAS controller can run the
network (Note: These **must** be installed if you later set the options in
the web interface to have MAAS manage DHCP/DNS). If you need to integrate your
MAAS setup under an existing DHCP setup, see :ref:`manual-dhcp`
 

Install packages
^^^^^^^^^^^^^^^^

At the command-line, type::

  $ sudo apt-get install maas maas-dhcp maas-dns

You will see a list of packages and a confirmation message to proceed. The
exact list will obviously depend on what you already have installed on your
server, but expect to add about 200MB of files.

The configuration for the MAAS controller will automatically run and pop up
this config screen:

.. image:: media/install_cluster-config.*

Here you will need to enter the hostname for where the region controller can
be contacted. In many scenarios, you may be running the region controller
(i.e. the web and API interface) from a different network address, for example
where a server has several network interfaces. 

Once the configuration scripts have run you should see this message telling
you that the system is ready to use:

.. image:: media/install_controller-config.*

The web server is started last, so you have to accept this message before the service is run and you can access the Web interface. Then there are just a few
more setup steps :ref:`post_install`

.. _disc-install:

Installing MAAS from Ubuntu Server boot media
---------------------------------------------

If you are installing MAAS as part of a fresh install it is easiest to choose
the "Multiple Server install with MAAS" option from the installer and have
pretty much everything set up for you.
Boot from the Ubuntu Server media and you will be greeted with the usual
language selection screen:

.. image:: media/install_01.*

On the next screen, you will see there is an entry in the menu called "Multiple
server install with MAAS". Use the cursor keys to select this and then press
Enter.

.. image:: media/install_02.*

The installer then runs through the usual language and keyboard options. Make
your selections using Tab/Cursor keys/Enter to proceed through the install.
The installer will then load various drivers, which may take a moment or two.

.. image:: media/install_03.*

The next screen asks for the hostname for this server. Choose something
appropriate for your network.


.. image:: media/install_04.*

Finally we get to the MAAS part! Here there are just two options. We want to
"Create a new MAAS on this server" so go ahead and choose that one.

.. image:: media/install_05.*

The install now continues as usual. Next you will be prompted to enter a
username. This will be the admin user for the actual server that MAAS will
be running on (not the same as the MAAS admin user!)

.. image:: media/install_06.*

As usual you will have the chance to encrypt your home directory. Continue
to make selections based on whatever settings suit your usage.

.. image:: media/install_07.*

After making selections and partitioning storage, the system software will 
start to be installed. This part should only take a few minutes.

.. image:: media/install_09.*

Various packages will now be configured, including the package manager and 
update manager. It is important to set these up appropriately so you will
receive timely updates of the MAAS server software, as well as other essential services that may run on this server.

.. image:: media/install_10.*

The configuration for MAAS will ask you to configure the host address of the
server. This should be the IP address you will use to connect to the server 
(you may have additional interfaces e.g. to run node subnets)

.. image:: media/install_cluster-config.*

The next screen will confirm the web address that will be used to the web
interface.

.. image:: media/install_controller-config.*

After configuring any other packages the installer will finally come to and
end. At this point you should eject the boot media.

.. image:: media/install_14.*

After restarting, you should be able to login to the new server with the
information you supplied during the install. The MAAS software will run automatically.


.. image:: media/install_15.*


**NOTE:** The maas-dhcp and maas-dns packages are not installed by default. If you want to have MAAS run DHCP and DNS services, you should install these packages::

 $ sudo apt-get install maas-dhcp maas-dns

And then proceed to the post-install setup below.

.. _post_install:

Post-Install tasks
==================
If you now use a web browser to connect to the region controller, you should
see that MAAS is running, but there will also be some errors on the screen:

.. image:: media/install_web-init.*

The on screen messages will tell you that there are no boot images present, 
and that you can't login because there is no admin user. 

Create a superuser account
--------------------------

Once MAAS is installed, you'll need to create an administrator
account::

  $ sudo maas createsuperuser

Follow the prompts to create the account which you will need to 
login to the web interface. Unless you have a special need, it is best to 
accept the default login name of `root`, as it is rather annoying if you 
forget the username (although you can simply run this command again to create
a new superuser).


Import the boot images
----------------------

MAAS will check for and download new Ubuntu images once a week.
However, you'll need to download them manually the first time::

  $ sudo maas-import-pxe-files

If you are using an HTTP proxy, bear in mind that the "sudo" will not
pass your http_proxy environment variable on to the script.  If that is
a problem, pass it on explicitly::

  $ sudo http_proxy=$http_proxy maas-import-pxe-files


Login to the server
-------------------

To check that everything is working properly, you should try and login to 
the server now. Both the error messages should have gone (it can take a 
few minutes for the boot image files to register) and you can see that 
there are currently 0 nodes attached to this controller.

.. image:: media/install-login.*


Configure DHCP
--------------

If you are using MAAS to control DHCP, you need to configure this using the 
commandline interface, first by :ref:`logging on to the server API <api-key>` 
and then :ref:`setting up the interface <cli-dhcp>` 
However, if you are manually configuring a DHCP server, you should take a 
look at :ref:`manual-dhcp`

Once everything is set up and running, you are ready to :doc:`start enlisting
nodes <nodes>`
