README for
Radar Analysis and Visualization Environment
  R  A  V  E

Anders Henja and Daniel Michelson
Swedish Meteorological and Hydrological Institute

March 2022

<caveats> 
RAVE has been developed on Ubuntu starting at version 8.04, and OSX. 
It has  been verified on a number of other systems too (see below). 
Your experiences may differ when building RAVE, and the software on
which it is dependent, on a different platform. Please collect your 
experiences and share them.

RAVE may work on proprietary unices but it is not designed for Windows.
</caveats>


INTRODUCTION
 
A stock Python build, together with a few extra third-party packages,
provides the basis for installing RAVE. When these are all installed,
building and installing RAVE can be done with a single "make" command
provided the correct environment variables are set.

Some systems bundle all third-party software together with their own
software. This has not been done for RAVE. The motivation for this is that
it should be possible to maintain and update the third-party software
without influencing RAVE, to the furthest extent possible.


VERIFIED SYSTEMS

RAVE is known to work on the following 64-bit systems:
Ubuntu 8.04 through 21.10
CentOS 7, RedHat 7, CentOS Stream 8 and RedHat 8 (Final)
Mac OSX 10.5 (Leopard), 10.6 (Snow Leopard), 10.8 (Mountain Lion)


ZLIB (optional)
---------------
Most 64-bit  Linux distributions contain this library. It is required for HDF5 
and the Python Imaging Library. Versions prior to 1.2.3 may contain a security
vulnerability. You should therefore verify the version on your system
before continuing. If you need to upgrade, get it at http://www.zlib.net/ .

Python >= 3.6 
----------------
The simplest way to install Python is to use the one shipped with the OS you are running.
Typically, "sudo apt-get install python3..." or "sudo yum install python3..."
If this is not possible you will have to download Python from python.org
RAVE has been verified to run on Python 3.6 up to 3.9. We still have kept the backward 
compatibility for Python 2.7 but this is nothing we actively maintain.

$ ./configure --prefix=<where you want it> 

$ make
$ make test
$ make install

Modify your $PATH in a .cshrc or .bash_profile so you don't run the wrong
Python.  

Numeric Python (NumPy) 1.14.2 (or higher)
----------------------------
Like with Python, preferred way to install NumPy is to use the version shipped with the OS.
Usually "sudo apt-get install python3-numpy" or "sudo yum install python3-numpy". If that doesn't
work use pip3 with: pip3 install "numpy==1.14.2"

PILLOW 5.0.0 (or higher)
----------------------------
Like with Python, preferred way to install Pillow (PIL) is to use the version shipped with the OS.
Usually "sudo apt-get install python3-pillow" or "sudo yum install python3-pillow". If that doesn't
work use pip3 with: pip3 install "pillow==5.0.0"

HDF5 1.8.5-patch1 or higher
---------------------------
Use the OS-supported version of hdf5 and install that. If you for some reason can't use that
you can download the software from hdfgroup and build it.

$ ./configure --prefix=<where you want it>
Useful but optional features: --enable-fortran --enable-cxx
--with-pthread --enable-threadsafe

$ make
$ make check
$ make install
$ (optionally) make check-install

LD_LIBRARY_PATH (reminder!)
---------------
Make sure your LD_LIBRARY_PATH points to the correct locations of Python
and HDF5! If you miss this step, then weirdness will happen!


HL-HDF and PyHL
---------------
Download the hlhdf.git package from https://github.com/baltrad/hlhdf.git and follow the 
directives in the INSTALL file.


PROJ.4 >= 4.7.0 or PROJ >= 6
------------
PROJ usually comes with the OS in some way and is the preferred software to use. If that doesn't work
you can download PROJ from https://proj.org/.

$ ./configure --prefix=<where you want it>
$ make
$ make install

Add <prefix>/lib to your LD_LIBRARY PATH and <prefix>/bin to your PATH if
you want to use the binary tools.

RAVE
----
Better late than never...

See the INSTALL file.


CONFIGURATION
-------------
In the 'config' directory, it is your responsibility to ensure that the
configuration files are up-to-date. If configuration files for your
country's radars, projections, and areas don't exist, then create them
using existing files as templates.

Radar configuration: <country>_radars.xml
Cartographic projections: <country>_projections.xml
Coverage areas: <country>_areas.xml

Read the TODO file to see how RAVE may evolve.


USING KEYCZAR KEYS
------------------
If you want to inject files into a BALTRAD DEX, you have to generate a key
for signing the messages. The following assumes you have installed the
Python package, but should be pretty much the same if you use the Java
package. We'll create an asymmetric DSA key and then export the public key
from it.

First, create a "store" for your key:

$ python -m keyczar.keyczart create \
    --location=/path/to/your/key \
    --purpose=sign \
    --name=keyname \
    --asymmetric=dsa

Then generate the key itself:

$ python -m keyczar.keyczart addkey \
    --location=/path/to/your/key \
    --status=primary

Then export the public key:

$ python -m keyczar.keyczart pubkey \
    --location=/path/to/your/key \
    --destination=/path/to/your/key.pub

The public key should then be put to the BALTRAD NODE installation at
etc/bltnode-keys/$DEX_NODENAME.pub. 

Remember to keep your private key (at /path/to/your/key) secret and safe!