To learn more about MARS and how to use it, please visit the MARS user documentation.

One of the big features of the European Weather Cloud is the fast access to data resources. If you want to access MARS from the European Weather Cloud, here is what you need to do.

Setting up your instance

For fast MARS access, you will need to provision your instance on the ECMWF cloud. In that case, ensure your instance has a public IP, either attaching it to the "external-internet" network, or alternatively use the private network in the tenant and add a Floating IP. 

Ubuntu and Rocky have support for native MARS client through the ECMWF Data flavour offered as part of the EWC Community Hub. This flavour turns a plain virtual machine into one that's ready to work with ECMWF data. It installs the MARS client along with a small toolkit for working with weather data (ecCodes, Metview, Earthkit).

Using the EWC CLI

You can deploy a new instance directly containing this flavour with the EWC CLI. For example, to create a new instance with the default values of flavours and instances:

ewc hub deploy --server-name myinstance ecmwf-data-flavour

You may deploy it on an existing instance using the existing name and settings such as the image name as well.

Using Ansible

If you prefer, you can just use Ansible directly to configure your instance. Before you start, make sure you have

  • An instance already running on the European Weather Cloud.
  • The SSH key you used to create that instance, saved somewhere on your computer
  • The instance's IP address
  • Ansible installed on your own machine (pip install ansible works if you have Python already)

Step 1: Download the playbook

This copies the setup instructions onto your computer.

git clone https://github.com/ewcloud/ewc-flavours.git
cd ewc-flavours/playbooks/ecmwf-data-flavour


Step 2: Install any extra dependencies the playbook needs

ansible-galaxy install -r requirements.yml

Step 3: Tell Ansible which instance to configure

Create a file called inventory.yml in this same folder, and fill in your instance's details:


---
ecmwf_data_flavour:
  hosts:
    my-instance:
      ansible_host: <your instance's IP address>
      ansible_user: <user for your image>
      ansible_ssh_private_key_file: <path to your SSH private key>
      ansible_python_interpreter: /usr/bin/python3
      ansible_ssh_common_args: -o StrictHostKeyChecking=accept-new

A couple of pointers:

  • Replace everything in < > with your own values.
  • If you're not sure what the default username is for your chosen image, check EWC Virtual Images Available

Step 4: Run it

ansible-playbook -i inventory.yml ecmwf-data-flavour.yml

This will connect to your instance over SSH and install everything. It usually takes a few minutes — you'll see a scrolling log of each step as it happens. If it finishes without any lines in red, it worked.

Configuring MARS

After having installed mars, you will need an extra step so MARS knows who you are when you issue your requests. 

  1. In your web browser...
    1. Go to https://apps.ecmwf.int/v1/key
    2. Log in with your ECMWF user and password if you are not logged int already
    3. Copy the contents of .ecmwfapirc, containing your email address and key.
  2. In your VM, create a file in your home directory called ~/.ecmwfapirc and paste the contents previously copied from the web.

Test your setup

You may only access data you have been granted access to. In some cases you may not be able to retrieve valid forecast data.

You may test your connection by any valid MARS request. You have a number of examples in MARS example requests. 

If you have access to real time data, a quick one-liner to test everything works is:

echo "retrieve, target=test.grib" | mars

The command should end with 0 exit code, a message stating "No errors reported" and a new file called test.grib containing 6 GRIB fields. You may decode them using ecCodes.