WMS Server Install

Information about setting up a new WMS server from scratch

This wiki covers the steps required to get an OpenSpace WMS (Web Map Server) configured & running. This serves MRF (Meta Raster Format) files. Another name for this service is AHTSE (An Httpd/apache Tile-Serving Engine).
This wiki covers the steps involved in importing WMS dataset(s) so that the AHTSE can serve tiles from the set. This wiki covers the steps involved in converting a raw raster image into the MRF format.

These instructions are specific to a linux server install.

Web Server Setup

Install the following software via the Operating System's package installer.

  1. Apache web server (version 2.4.23 or higher is required).
  2. GDAL (version 2.1.3 or higher is recommended).

Install the four MRF modules (mrf, receivef, sfim, reproject), which run as modules in the Apache web server. For each module, it is necessary to download the source code, compile the module, and configure Apache to run the module. The steps are similar for all modules, so instructions are given first for the mod_mrf module, and then any differing or specific information is provided for the others in subsequent sections. Note: The mrf module depends on the mod_receive module, which has to be installed first.

Add the mod_mrf module

  1. Clone the source code repository using the following command:
    git clone https://github.com/lucianpls/mod_mrf.git

  2. In the src/ directory, create a Makefile by copying from the provided example:
    cp Makefile.lcl.example Makefile.lcl

  3. Edit Makefile.lcl modify the include paths (if needed) to reflect the INCLUDES include paths for apache2 on the server. Also edit the MOD_PATH to match where apache2 modules are located on the filesystem. This is a typical example:

INCLUDES = -I /usr/include/apache2 -I /usr/include/apr-1
MOD_PATH = /usr/lib64/apache2/

On some systems, the apache module path might be /etc/httpd/modules or /usr/lib/apache2/modules. Note that the names apache2 and httpd are sometimes used interchangeably.

  1. Type make to build the module, and make install to install the resulting library file (for example, mod_mrf.so on linux) to the apache modules location. Prefacing this with sudo may be required.

  2. Add the module to Apache's module loader config file by editing the file /etc/apache2/loadmodule.conf and adding the following line at the end:
    LoadModule mrf_module /usr/lib64/apache2-prefork/mod_mrf.so
    Note the -prefork in the path, and make sure that this path matches the apache2 install path on the system. In other words, add -prefork to the end of the MOD_PATH from your Makefile, and then verify that the resulting path exists on the filesystem. This is a directory created by Apache at runtime, so it may be necessary to restart on a system where Apache was newly installed. At startup, Apache takes the modules from the MOD_PATH location and copies them to the prefork directory.
    Note: On Ubuntu 16.04, no -prefork is created and the so file is placed in the same directory as specified

  3. Add the mrf module to the list of APACHE_MODULES in the file /etc/sysconfig/apache2. This is a space-delimited list of modules. Note that the module names do not have the mod_ prefix or the .so suffix, so just add mrf to the end of this line. (Note: This does not seem to exist on Ubuntu 16.04)

  4. Restart Apache using the command:
    sudo service apache2 restart

  5. Verify that the module is loaded by typing:
    sudo apachectl -M
    There should be a mrf_module line in the listing. If not, troubleshoot the above steps.
    Another way to list running modules is to use a browser to view the Apache server info page http://localhost/server-info. Some Apache installs do not provide the server module required to view this page by default. If the page does not load, it is probably because the info module isn't loaded in Apache. To add this module, add the following line to /etc/apache2/loadmodule.conf:
    LoadModule mod_info_module /usr/lib64/apache2-prefork/mod_info.so
    and also add info to the APACHE_MODULES line in /etc/sysconfig/apache2. Finally, restart apache2 using the command in the previous step.

Add the mod_receivef module

  1. Clone the source code repository using the following command:
    git clone https://github.com/lucianpls/mod_receive.git

  2. Same as MRF example above.

  3. Same as MRF example above. The HTTPD_INCLUDES_PATH entry is just /usr/include/apache2, or whatever the main apache2 include path is in INCLUDES, depending on the system.

  4. Same as MRF example above.

  5. It does not appear to be necessary to add a LoadModule command to /etc/apache2/loadmodule.conf for this module.

  6. Add receive to the list of APACHE_MODULES in the /etc/sysconfig/apache2 file.

  7. Restart Apache.

  8. Verify that the receive_module is listed in the apachectl -M output.

Add the mod_sfim module

  1. Clone the source code repository using the following command:
    git clone https://github.com/lucianpls/mod_sfim.git

  2. Same as MRF example above.

  3. Same as MRF example above, but only MOD_PATH variable path is required.

  4. Same as MRF example above.

  5. It does not appear to be necessary to add a LoadModule command to /etc/apache2/loadmodule.conf for this module.

  6. Add sfim to the list of APACHE_MODULES in the /etc/sysconfig/apache2 file.

  7. Restart Apache.

  8. Verify that the sfim_module is listed in the apachectl -M output.

Add the mod_reproject module

  1. Clone the source code repository using the following command:
    git clone https://github.com/lucianpls/mod_reproject.git

  2. Same as MRF example above.

  3. Same as MRF example above.

  4. Same as MRF example above. Building this module requires the development (includes headers) versions of the libraries libapr-1 and libjpeg. Install these using the OS package manager if necessary.

  5. It does not appear to be necessary to add a LoadModule command to /etc/apache2/loadmodule.conf for this module.

  6. Add reproject to the list of APACHE_MODULES in the /etc/sysconfig/apache2 file.

  7. Restart Apache.

  8. Verify that the reproject_module is listed in the apachectl -M output.

At this point, the system is ready to operate as a WMS tile-serving engine.

Configure Apache Virtual Host to Serve MRF Data

The Apache server has a directory from which web content is served. This can be the default directory based on the install, or Apache can be configured with a Virtual Host that has special behavior based on the address of received requests. AHTSE is configured to provide this behavior for the WMS data.

Configuring Apache with a Virtual Host is optional for AHTSE. However, it provides flexibility with the web server so that it can be used for different types of content if so needed. Some of the following steps would still be needed without a Virtual Host setup.

  1. Add a configuration file in Apache's virtual hosts directory (e.g. /etc/apache2/vhosts.d/) by copying & renaming a template file provided in the install (e.g. vhost.template).

  2. Modify the <VirtualHost> tag to match the hostname or URL that you want to be directed to AHTSE requests.

  3. Set <DocumentRoot> to the Apache web content directory structure containing the .wms files. See the wiki on importing MRF data sets, ".wms file" section for more information.

  4. Add specific detail to <Directory> tag, including where .wms files are located in the Apache web content directory, server options, permissions.

  5. Set log file locations for logging accesses and errors.

Here is an example from the Utah server configuration file /etc/apache2/vhosts.d/openspace.conf:

#(IP address below is fake)
<VirtualHost 000.000.000.000:80>
    ServerName openspace.sci.utah.edu
    DocumentRoot /srv/www/vhosts/openspace
    HostnameLookups Off
    UseCanonicalName Off
    ServerSignature Off
    <IfModule mod_userdir.c>
        UserDir public_html
        Include /etc/apache2/mod_userdir.conf
    </IfModule>
    <Directory "/srv/www/vhosts/openspace">
        Options Indexes FollowSymLinks
        AllowOverride None
        <IfModule !mod_access_compat.c>
            Require all granted
        </IfModule>
        <IfModule mod_access_compat.c>
            Order allow,deny
            Allow from all
        </IfModule>
    </Directory>
    ErrorLog /var/log/apache2/openspace/openspace_error_log
    LogLevel error
    TransferLog /var/log/apache2/openspace/openspace_access_log
</VirtualHost>