"Deploy a Baserock system" tutorial


  • Show how to deploy the system we have built
  • Introduce the related help and reference documentation

Task(s) to be completed

  • Deploy and run a built system

Start state

The end state of the "Build a system and debug a failing build" tutorial

  • a functioning development environment
  • a populated Trove
  • a populated artifact cache
  • a built Baserock system
  • somewhere we can deploy the built system

End state

  • the built system is deployed and running


  • run morph deploy with the correct arguments

The Build a Baserock System section of the Developing with Baserock page at baserock.org shows how to deploy to a VM. To see how to deploy to a real server deployment node, we need a bit more

# morph help deploy
Usage: morph [options] deploy TYPE SYSTEM LOCATION [KEY=VALUE]

Deploy a built system image.

Command requires a minimum of three arguments:


* TYPE is type of deployment
* SYSTEM is name of the system morphology to deploy
* LOCATION is the destination of the deployed system

For more details we can look at the morph deploy section of the Morph Reference Manual.

// To do: we need information about the nfs-boot write extension: how to use it and what it expects from the server

// To do: get the correct content in the command output below

The command we need to run is

bash-4.2# morph deploy --no-git-update nfsboot base-system-armv7-versatile \

Show the built system running.

Posted Fri Oct 17 13:21:40 2014

Tutorial 1.3 - "Deploy a Baserock system"

In this tutorial we are going to learn how to deploy a system that we have built.

The starting point for this tutorial is the point we got to at the end of the last tutorial. We now have:

  • a functioning development environment
  • a built Baserock system

We also need somewhere to deploy the system. The public Baserock documents describe how to deploy a system to a Virtual Machine that can be run in VirtualBox, but we are going to deploy to a deployment node on the server.

To do this we use the morph deploy command. Let's look at morph help deploy

# morph help deploy
Usage: morph [options] deploy TYPE SYSTEM LOCATION [KEY=VALUE]

Deploy a built system image.

Command line arguments:

* `TYPE` is the type of deployment: to a raw disk image, VirtualBox, or
  something else. See below.

* `SYSTEM` is the name of the system morphology to deploy.

* `LOCATION` is where the deployed system should end up at. The syntax depends
  on the deployment type. See below.

* `KEY=VALUE` is a configuration parameter to pass onto the configuration
  extension. See below.

It goes on to list a subset of the deployment options, but for deploying a system we need to make the following substitutions:

  • TYPE -> nfsboot
  • SYSTEM -> base-system-armv7-highbank is the name of the system we want to deploy. For big-endian it's base-system-armv7b-highbank
  • LOCATION to 'blbg-1' which is the address of the Trove

We'll add the following KEY/VALUE pairs which are required for nfsboot deployments

  • NFSBOOT_CONFIGURE=yes is currently needed when nfs booting to change some network and file system config. If this is forgotten then the system will lock up some time during boot.
  • HOSTNAME=box-1-node-2 to box-1-node-15, determines which node will have its root file system replaced. Nodes 0 and 1 are reserved, nodes 10 to 15 are suggested.
  • VERSION_LABEL=test-deploy-1 is used to version the systems that have been deployed to a node, so rolling back to a previous one is possible. This needs to be unique or deployment will fail.

    We recommend you include your initials and the date if you are unsure.

The deploy command line syntax is cumbersome, so it is recommended to write a short script rather than enter it directly every time.

bash-4.2# cat >nfs-deploy.sh <<\EOF
exec morph deploy --no-git-update nfsboot "$SYSTEM" blbg-1 \
bash-4.2# chmod +x nfs-deploy.sh

Now we can execute the script to deploy it

bash-4.2# ./nfs-deploy.sh base-system-armv7-highbank box-1-node-10 \
2013-05-28 14:41:01 Starting build 95dfab373eef4cbb948c45cd6f846107
2013-05-28 14:41:01 Collecting morphologies involved in building base-system-armv7-highbank from master
2013-05-28 14:41:01 baserock:baserock/morphs: Creating build branch
2013-05-28 14:41:01 baserock:baserock/morphs: Adding uncommitted changes to build branch
2013-05-28 14:41:01 baserock:baserock/morphs: Update morphologies to use build branch instead of "master"
2013-05-28 14:41:01 Figuring out the right build order
2013-05-28 14:41:27 Unpacking system for configuration
2013-05-28 14:42:34 System unpacked at /src/tmp/tmpMnbtzg

Morph runs configuration extensions. These are scripts that take parameters from the command line and alter the target system to configure it before it is written to the target device.

2013-05-28 14:42:34 Configure system
2013-05-28 14:42:38 Running extension set-hostname.configure
2013-05-28 14:42:38 Running extension ssh.configure
No SSH key directory found.
2013-05-28 14:42:40 Running extension add-config-files.configure

Morph then runs the write extension called nfsboot. This copies the configured system to the Trove and configures the target node to boot it.

This runs multiple commands over ssh, so passwords may need to be entered multiple times.

2013-05-28 14:42:40 Writing to device
2013-05-28 14:42:40 Running extension nfsboot.write
2013-05-28 14:42:46 Creating destination directories
2013-05-28 14:42:46 Creating 'orig' rootfs
2013-05-28 14:43:26 Creating 'run' rootfs
2013-05-28 14:43:30 Linking 'default' to latest system
2013-05-28 14:43:30 Copying kernel
2013-05-28 14:43:30 Creating links to kernel in tftp directory
2013-05-28 14:43:33 Cleaning up
2013-05-28 14:43:41 Finished deployment

Rebooting the node

To finish the nfsboot deployment we need to restart the node. The following commands assume we're deploying to node 10, change the ip-address for your node using the formula in the Accessing cluster nodes tutorial.

First attempt to log in over SSH to shut it down cleanly with.

$ ssh -A -l root -p 9041 blbg-1 reboot

If this fails then log in over the console port with the following commands and tell it to reboot.

$ ssh -A -l root cxmanage
# ipmitool -U admin -P admin -H -I lanplus sol activate

If all else fails, turn it off and on again with the following commands

$ ssh -A -l root cxmanage
# ipmitool -U admin -P admin -H chassis power off
Chassis Power Control: Down/Off
# ipmitool -U admin -P admin -H chassis power on
Chassis Power Control: Up/On

After the machine has rebooted log on to the console port by running the following command.

# ipmitool -U admin -P admin -H -I lanplus sol activate

You eventually be left with a login prompt. You should be able to log in as root without a password. You need to set one before you are able to log in over SSH.

As mentioned in the Accessing cluster nodes tutorial, you should then be able to access it over ssh with the following command.

$ ssh -A -l root -p 9041 blbg-1

Other deployment configuration

We only gave the minimum to get a system NFS booting before. There are numerous other options that need to be documented.

You may have a script called deploy-highbank-devel-system.sh in your morphs repository, this wraps the morph deploy command and sets some other useful defaults. If you run it as follows then it will set up ssh keys and other configuration, like DNS resolver configuration.

bash-4.2# ./deploy-highbank-devel-system.sh base-system-armv7-highbank \
              box-1-node-10 test-deploy-2
Posted Fri Oct 17 13:21:40 2014