Table of contents:
- Software Requirements
- Setting up the Default Virtual Machine
- Using the Default Virtual Machine
- Disabling the Desktop Environment
- Using other Virtual Machines
- Optional Windows Software
In order to use a virtual machine (VM), you must first install:
- VirtualBox, software that enables running of virtual machines (version 5.1.6 or later required).
- Vagrant, software that allows easy configuration of virtual machines (version 1.9.1 or later required).
These applications provide point-and-click installers for Windows and can usually be installed via the package manager on Linux systems.
Setting up the Default Virtual Machine
After you have installed VirtualBox and Vagrant, download the metomi VM setup files from github:
Then extract the files which will be put into a directory called
The default VM uses Ubuntu 16.04.
If necessary you can customise the VM by editing the file
Vagrantfile.ubuntu-1604 as follows:
- By default the VM will be built with support for accessing the Met Office Science Repository Service.
If you don't want this (or don't have access) then remove
- As described below, you may prefer not to install the desktop environment.
To do this remove
config.vm.provisionline and comment out the line
v.gui = true.
- By default the VM is configured with 1 GB memory and 2 CPUs. You may want to increase these if your host machine is powerful enough.
See the Vagrant documentation for more details on configuration options.
Before proceeding you need to be running a terminal with your current directory set to
- Windows users can navigate to the directory using Windows File Explorer and then use
Shift-> Right Mouse Click -> Open command window here.
Now run the command
vagrant up to build and launch the VM.
This involves downloading a base VM and then installing lots of additional software so it can take a long time (depending on the speed of your internet connection).
Note that, although a login screen will appear in a separate window, you will not be able to login at this stage.
Once the installation is complete the VM will shutdown.
Using the Default Virtual Machine
Run the command
vagrant up to launch the VM.
A separate window should open containing a lightweight Linux desktop environment (LXDE) with a terminal already opened.
If your VM includes support for the Met Office Science Repository Service then you will be prompted for your password (and also your user name the first time you use the VM).
If you get your username or password wrong and Subversion fails to connect, just run
mosrs-cache-password to try again.
The VM is configured with a local Rose suite repository and with the suite log viewer running under apache. If you want to learn more about Rose and Cylc you can follow the tutorials contained in the Rose User Guide.
To shutdown the VM you can either use the menu item available in the bottom right hand corner of the Linux desktop or you can issue the command
vagrant halt from the command window where you launched the VM.
Note that the desktop environment is configured to use a UK keyboard.
If you need to change this, take a look at how this is configured in the file
Disabling the Desktop Environment
If you are using the VM on a Mac or Linux system where you already have a X server running then you may find it easier to not install the desktop environment.
In order to do this, edit the file
Vagrantfile.ubuntu-1604 as described above.
Then run the command
vagrant up to launch the VM in the normal way.
Note that, unlike when installing the desktop environment, it will not shutdown after the initial installation.
Once the VM is running, run the command
vagrant ssh to connect to it.
To shutdown the VM you can either run the command
sudo shutdown -h now from within your ssh session or you can exit your ssh session and then issue the command
Using other Virtual Machines
In addition to the default VM, additional VMs are supported in separate files named
These other VMs are provided primarily for the purpose of testing FCM, Rose & Cylc on other Linux distributions and providing a reference install on these platforms.
Note that they are not as well tested as the default VM and may not include a desktop environment.
To use a different VM, modify the file which is loaded in the default
Vagrantfile before running
Alternatively you can set the environment variable
VAGRANT_VAGRANTFILE, for example:
set in place of
export when using the command window on Windows).
Optional Windows Software
For an alternative to the normal command window, Windows users can install Git BASH (which comes with Git for Windows). As well as providing a nicer interface (more familiar for Linux users) this also means that you can use git to clone the metomi-vms repository (instead of downloading the zip file):
git clone https://github.com/metomi/metomi-vms.git
It is then easy to track any local changes, pull down updates, etc.
If you want to run a VM without a desktop environment on Windows then, in order to enable GUI programs to work, you will need to install Cygwin, making sure to select the
xorg-server packages from the
X11 section and the
openssl packages from the
Then, instead of using a normal command window for launching the VM, you should use a Cygwin-X terminal, which you can find in the Start Menu as
Cygwin-X > XWin Server.
In Cygwin-X terminals, you can use many common Unix commands (e.g. cd, ls).
Firstly run the command
cd /cygdrive followed by
ls and you should see your Windows drives.
Then use the
cd command to navigate to the directory where you have extracted the setup files (e.g.
Guest display resolution
When you resize the VirtualBox window (e.g. to mazimise it) the display resolution of your Linux VM should adjust to match.
If this doesn't work it may be due to the Guest Additions installed in your VM not matching the version of VirtualBox you have installed.
The easiest way to fix this is to install the vagrant-vbguest Vagrant plugin.
Note that, if the plugin does update your Guest Additions then you will need to shutdown and restart your VM (using
vagrant up) in order for them to take effect.