Quick Start

This page describes how to setup a Baserock x86 development virtual machine and make it ready to use. If you just want to get going as fast as possible, you can cut-and-paste the commands as shown in this video.

If you want to try Baserock on other Linux systems or in the cloud, check out ybd.

Set up the baserock VM

Follow these steps to setup a Baserock x86 virtual machine and make it ready to use.

We provide a build system image; you will need to upgrade to the development system, which has development tools installed. We do not provide the development system image as a download, due to issues of size and speed. The section 'Upgrade your baserock VM to a devel VM' below gives details of how to do the upgrade.

Follow the instructions in the 'Create a Baserock VM' guide to create and run the baserock VM.

Alternatively see

Login to the baserock VM

Now the VM is running and displaying a console window, you can log in, set a password, and setup SSH access.

To login, type root at the VM's Login prompt.

Use passwd to set a password.

The VM will now be accessible via the host using ssh. The VM uses DHCP to get an IP address automatically. To see what IP address was assigned, type ip addr.

We normally ssh into a Baserock VM and work there. Putting ssh keys into the VM is not a good idea so, having set a nominal password for root on the VM itself, on your host, using VirtualBox you can

ssh -A root@vm.ip.address

or if you are using KVM or QEMU

ssh -A -p5555 root@localhost

Then, to be able to ssh from your VM back to your host without being asked for a password each time, in the host run

ssh-copy-id root@vm.ip.address

or if you are using KVM or QEMU

ssh-copy-id -p5555 root@localhost

(The above steps assume that you already have ssh keys on your host machine. If you don't you will need to run ssh-keygen - and accept the defaults - before you run them.)

You should now be able to use your host key(s) from within the VM during your session, and login to the VM from your host without entering a password. (See Using ssh-agent to manage your keys for description of what ssh-add does)

Add a /src partition to your VM

It's a good idea to have a separate partition for storing git caches and the artifacts morph will produce when you run a morph build. Morph by default needs at least 8GB for building/deploying systems. In practice you will want much more than this, the exact amount depends on usage, but typically something between 50 and 100GB is recommended.

To format with ext4:

mkfs.ext4 -L src /dev/sdb
mkdir /src

then add this line to /etc/fstab:

LABEL=src /src ext4 defaults 0 2

Reboot. /dev/sdb should now be mounted under /src.

Configure Morph

This step is applicable to [Baserock chroot|guides/chroot] users as well.

Morph is Baserock's build tool. It comes installed with the Baserock build system.

If you want to use 'bleeding edge morph' see using the latest Morph. If you intend to upgrade your build system to a devel system, as per the instructions in the later section, you must upgrade to the latest version of morph.

Before building, you should create a configuration file for Morph. We recommend that the configuration file is stored in /src/morph.conf and it should contain the following:

log = /src/morph.log
log-max = 200M
cachedir = /src/cache
tempdir = /src/tmp
# optionally get artifacts from cache, rather than build them
# this should be faster (unless you have a very slow network)
artifact-cache-server = http://cache.baserock.org:8080/

Then create a symlink to it from /etc:

ln -sv /src/morph.conf /etc/morph.conf

This way if you replace your root disk you only need to re-create the symlink.

By default, Morph will use git.baserock.org as its Trove. To configure Morph to use a different Trove, add a trove-host line in your morph.conf e.g.

trove-host = my-trove.my-domain.co.uk

Configure your Git identity

This step is applicable to [Baserock chroot|guides/chroot] users as well.

Since Baserock uses git to track most things, you must configure git on the VM to use your name and email address:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

If you fail to do this, then many of morph's commands will display a warning and/or refuse to operate until you configure git correctly.

Accessing Baserock guest VM filesystem from host via sshfs

If you want to use tools from your host machine when working with files on your Baserock guest VM, you can run sshfs on your host, to set up a mount on the client's filesystem.

For example, on a mac, running the following would allow you to browse and edit files on your guest Baserock /src partition directly from your MacOS host.

mkdir ~/baserock-src
sshfs root@vm.ip.address:/src /Users/<your-username>/baserock-src

If you are using KVM, the following will mount the /src directory in the VM to /vm-src in the host

sshfs -o idmap=user root@IP:/src /vm-src

Another solution with VirtualBox is configuring VB to proxy the ssh port locally, then running

sshfs -o idmap=user,port=12345 root@localhost:/src /vm-src

FIXME: Some more details about this may be useful

Upgrade your baserock VM to a devel VM

Your VM is currently a build system; to use many development tools, you now need to upgrade it to a devel system.

This is a quick guide to get you going with a devel system. Upgrading Baserock systems is described in detail in the 'upgrading Baserock systems' guide.

First, get the build instructions (definitions) for the Baserock reference systems. You can use any clone of definitions.git.

git clone git://git.baserock.org/baserock/baserock/definitions --branch baserock-16.13
cd definitions

Second, build it:

morph build systems/devel-system-x86_64-generic.morph

Now use clusters/upgrade-devel.morph to deploy the result of that build as an upgrade to your system. Choose a version label that makes sense to you: 'devel' is fine, but some people use the current date as the version label, or other things. The label you choose must be valid as a filename.

NOTE: Ensure that your root user has passwordless SSH access to with ssh root@ whoami. If not, run ssh-copy-id root@

morph upgrade clusters/upgrade-devel.morph self.HOSTNAME=$(hostname) self.VERSION_LABEL=devel

If the deployment succeeded, you'll find that system-version-manager list shows two versions: 'factory' and 'devel'. The running system should be 'factory' (this is the initially deployed version, the name comes from 'factory default'). The default system should now be 'devel', meaning that when you reboot your VM it will boot into the 'devel' version, which will contain some extra components, such as those in the devtools stratum.

See the 'upgrading Baserock systems' guide for more information about upgrades.

Now what?

You are now ready to start using Baserock. Basic development tools (gcc, make, vim, git) are installed. Go to Using Baserock to learn how to develop systems with Baserock.

Here are some ideas for things you might want to do, and a guide to contributing.