Installing h5serv¶
You should find h5serv quite easy to setup. The server (based on Python Tornado) is self-contained, so you will not need to setup Apache or other web server software to utilize h5serv.
Prerequisites¶
A computer running a 64-bit version of Windows, Mac OS X, or Linux.
You will also need the following Python packages:
- Python 2.7
- NumPy 1.9.2 or later
- h5py 2.5 or later
- PyTables 3.1.1 or later
- tornado 4.0.2 or later
- twisted 14.0 or later (if setting up DNS)
- requests 2.3 or later (for client tests)
If you are not familiar with installing Python packages, the easiest route is to use a package manager such as Anaconda (as described below).
If you have a git client installed on your system, you can directly download the h5serv
source from GitHub: git clone --recursive https://github.com/HDFGroup/h5serv.git
.
Otherwise, you can download a zip file of the source from GitHub (as described below).
Installing on Windows¶
Anaconda from Continuum Analytics can be used to easily manage the package dependencies needed for HDF Server.
In a browser go to: http://continuum.io/downloads and click the “Windows 64-bit Python 2.7 Graphical Installer” button.
Install Anaconda using the default options.
Once Anaconda is installed select “Anaconda Command Prompt” from the start menu.
In the command window that appears, create a new anaconda environment using the following command:
conda create -n h5serv python=2.7 h5py twisted tornado requests pytz pytables
Answer ‘y’ to the prompt, and the packages will be fetched.
In the same command window, run: activate h5serv
In a browser go to: https://github.com/HDFGroup/h5serv and click the “Download ZIP” button (right side of page). Save the file as “h5serv.zip” to your Downloads directory.
Alternatively, if you have git installed, you can run:
git clone --recursive https://github.com/HDFGroup/h5serv.git
to download the h5serv source tree.
If you downloaded the ZIP file, in Windows Explorer, right-click on the file and select “Extract All...”. You can choose any folder as the destination.
Next, in the command window, cd to the folder you extracted the source files to.
From here cd to “h5serv-master/server”.
Run: python app.py You should see the output: “Starting event loop on port: 5000”.
You may then see a security alert: “Windows Firewall has blocked some features of this program”. Click “Allow access” with the default option (Private network access).
At this point the server is running, waiting on any requests being sent to port 5000. Go to the “verification” section below to try out the service.
Installing on Linux/Mac OS X¶
Anaconda from Continuum Analytics can be used to easily manage the package dependencies needed for HDF Server.
In a browser go to: http://continuum.io/downloads and click the “Mac OS X 64-bit Python 2.7 Graphical Installer” button for Mac OS X or: “Linux 64-bit Python 2.7”.
Install Anaconda using the default options.
Once Anaconda is installed, open a new shell and run the following on the command line:
conda create -n h5serv python=2.7 h5py twisted tornado requests pytz pytables
Answer ‘y’ to the prompt, and the packages will be fetched.
In the same shell, run: source activate h5serv
Run: git clone --recursive https://github.com/HDFGroup/h5serv.git
to download the h5serv source
tree. Alternatively, in a browser go to: https://github.com/HDFGroup/h5serv and click
the “Download ZIP” button (right side of page). Download the zip file and extract to
the destination directory of your choice.
Next, cd to the folder you extracted the source files to.
From here cd to “server” (or “h5serv-master/server” if you extracted from ZIP file).
Run: python app.py
You should see the output: “Starting event loop on port: 5000”.
At this point the server is running, waiting on any requests being sent to port 5000. Go to the “verification” section below to try out the service.
Verification¶
To verify that h5serv was installed correctly, you can run the test suite included with the installation.
Open a new shell (on Windows, run “Annaconda Command Prompt” from the start menu).
In this shell, run the following commands:
- source activate h5serv (just: activate h5serv on Windows)
- cd <h5serv installation directory>
- cd test
- python testall.py
All tests should report OK.
Server Configuration¶
The file h5serv/server/config.py provides several configuration options that can be used to customize h5serv. Each of the options can be changed by:
- Changing the value in the config.py file and re-starting the service.
- Passing a command line option to app.py on startup. E.g.
python app.py --port=7253
- Setting an environment variable with the option name in upper case. E.g.
export PORT=5000; python app.py
The config options are:
port¶
The port that h5serv will listen on. Change this if 5000 conflicts with another service.
Default: 5000
debug¶
If True
the server will report debug info (e.g. a stack trace) to the requester on
error. If False
, just the status code and message will be reported.
Default: True
datapath¶
A path indicating the directory where HDF5 will be be stored.
Note: Any HDF5 file content that you put in this directory will be exposed via the server REST api.
Default: ../data/
hdf5_ext¶
The extension to assume for HDF5 files. The rest requests don’t assume an extension, so a request such as:
GET /
HOST: tall.data.hdfgroup.org
Translates to: “Get the file tall.h5 in the directory given by datapath”.
Default: .h5
local_ip¶
This option is used by the local_dns service. Should be the IP address of the server
hosting the h5serv service, or 127.0.0.1
if both local_dns and h5serv are running
on the same host.
Default: 127.0.0.1
default_dns¶
This option is used by the local_dns service. Should be the IP address of the normal DNS server for the local network.
Data files¶
Copy any HDF5 files you would like exposed by the service to the datapath directory (h5serv/data). If you do not wich to have the files updatable by the service make the files read-only.
Note: Do not modify files once they have been placed in the datapath directory. h5serv inventories new files on first access, but won’t see some changes (e.g. new group is created) made to the file outside the REST api.