Hyrax - Installation Instructions
Hyrax is really fairly easy to configure, but because there are several different components involved, it can seem complicated. Essentially you need to configure the BES to load and use one or more data handlers and to look in the right place for your data. The OLFS will work out of the box, but will need configuration to enable THREDDS functionality and Access Logging. Similarly, Tomcat needs no configuration, although you might want to change the port from 8080 to 80 if it's going to be the only web server on your host. You don't need to do that, it's just that you can if you want. Lastly, you can configure an Apache server to hand off requests to the server and, at the same time, have it emulate all your old Server3 URLs. That way catalogs, hot lists and other places where URLs to your data are stored will still work. This is not a complete manual for the BES. Instead of explaining all of the parameters and how their different settings can be used to control the BES, the discussion here is limited to what is used when the BES is run as part of Hyrax. In addition, there are number of parameters that should always be left to their default values for a Hyrax configuration and those will also be skipped. This makes it much easier to focus on those parameters that an installer really must understand.
What you will need:
- 30 minutes
- Java 1.5 Runtime or Development Environment
- Tomcat 5.5.x or newer
- A web browser
1 System Requirements
Hyrax is supported on Linux (our standard build platform is Fedora Core, we build our RPMs on CentOS 5.3 and we do also test on Ubuntu) and OS/X. It's certainly likely that you can get it to run on virtually any Unix-like operating system. We do not support Hyrax on Windows or Vista, although see the Using Virtual Machines to Serve Data project for a solution for Win32 platforms. Also a group at Microsoft Research has ported Hyrax 1.5.x to their Azure cloud platform.
You can use either yum, rpm or apt-get to get binary packages for all of the required software listed below. On many operating systems the only packages you'll need to get are those specific to data you intend to serve (e.g., hdf5). If you're building our source distributions, be sure to get the -devel' packages; if you're using our binary builds then the plain packages will be fine.
In general, in addition to the software needed to build/run the basic framework, to serve data stored in a particular format, you need a handler that can read that format and often you need a that format's software library.
1.1 For the impatient
On Linux system that uses RPM packages (Red Hat, CentOS, Fedora Core, ...), use yum to install libicu, netcdf, hdf4 and hdf5. Then install our packages.
To build from source, install libxml2-devel, libcurl-devel, uuid-devel, readline-devel, libicu-devel, netcdf-devel, hdf4-devel and hdf5-devel. Build. Your machine might have some of those packages, but RPM/yum will sort that out.
On systems that use the Debian package system, use apt-get to install the same packages, except that the development packages (the ones you need to compile code) are called -dev instead of -devel.
1.2 Short list
- libxml2 2.6.16*
- libcurl 7.10.6*
- pthreads (part of glibc on linux)*
- dap-server (referred to as General purpose handlers on download page)
- Tomcat 6.0.x
- Java 1.5* run-time (or newer, depending on the requirements of the Tomcat software).
1.3 Additional stuff
When building from source, to run tests:
To serve NetCDF files:
- The netCDF handler
- libnetcdf 3.x
To serve HDF4 files:
- The HDF4 handler
- The HDF4 library (4.x) and it's required software (often libjpeg, zlib* and szip)
To serve formatted ASCII using FreeForm:
- The FreeForm handler
To serve HDF5 files:
- The HDF5 handler
- The HDF5 library (1.6.0 or 1.8.x) (and often zlib*)
To provide data responses as NetCDF files:
- The Fileout NetCDF handler
- libnetcdf 3.x
To use NCML:
- The NCML Handler
- libicu 3.6
- At least one data handler
*Stock on any recent linux or OS/X distribution
2 Secure Installation Guidelines
3 Install the BES
4 Install the OLFS
5 Starting and Stopping Hyrax
To correctly start and stop Hyrax, follow these simple recipes.
- Start the BES first using the besctl program with the start argument. See Starting and stopping the BES for more information.
- Start the OLFS using the Tomcat startup script. See Starting Tomcat for more information.
- Stop the OLFS first using the tomcat shutdown script.
- Stop the BES using the besctl program with the stop argument.
See above for stopping information.
6 Test the server
To test/use the server, open a web browser and open the URL: http://localhost:8080/ and you should see the Tomcat default page.
Open the URL: http://localhost:8080/opendap/ to see an HTML directory of the top of your data archive.
You can get the HTML view THREDDS catalog by appending "catalog.html" to the end of any URL that returns an HTML directory, like so: http://localhost:8080/opendap/catalog.html But you may need to do some additional configuration that to work.
7 Configure Your Hyrax Installation
At this point, Hyrax should be working. When you install Hyrax for the first time it is pre-configured to serve test data sets that come with each of the installed data handlers. This will allow you to test the server and make sure it is functioning correctly. After that you will want to configure so that it works with your data.
Once opendap.war is expanded, manually copy the file favicon.ico file:
The favicon.ico file is mostly a convenience to keep browsers from constantly asking for it (substitute your own icon if you like!).