Map Layers - local UNIX Installation

Follow the notes in this section if the web server is running on the same machine as the one on which EMu server is installed:

1. Log in as emu.
2. Download the maps file maps.tar.gz. The maps should be saved in a temporary directory (typically /tmp). The download will take some time as the map files are very large (about 900 Mb).
3. Enter client  clientname
4. Enter tar  xvzf  /tmp/maps.tar.gz
   The maps will be extracted into the web/webservices/mapper/maps directory.
5. Enter rm  -f  /tmp/maps.tar.gz
6. Log out.
7. Continue with EMu WebServices - MapServer Installation.

Map Layers - remote UNIX Installation

Follow the notes in this section if the web server is running on a different machine to the one on which EMu server is installed:

1. Log in as root on the web server machine.
2. Download the maps file maps.tar.gz. The maps should be saved in a temporary directory (typically /tmp). The download will take some time as the map files are very large (about 900 Mb).
3. Enter cd  documentroot
   where documentroot is the DocumentRoot directory set in the Apache configuration file httpd.conf.
4. Enter mv  emuwebclientname  web
5. Enter tar  xvzf  /tmp/maps.tar.gz
   The maps will be extracted into the web/webservices/mapper/maps directory.
6. Enter mv  web  emuwebclientname
7. Enter rm  -f  /tmp/maps.tar.gz
8. Enter chown  -R  owner:group  emuwebclientname
   where owner and group are the owner name and group name respectively for files accessible by Apache. See the User and Group settings in the Apache configuration file httpd.conf for the correct values.
9. Log out.
10. Continue with EMu WebServices - MapServer Installation.

MapServer Installation

Once the maps are installed the MapServer PHP extension must be added. Unfortunately the procedure for installing MapServer is dependent on the version of UNIX. The notes below cover a range of UNIX variants. Please select the instructions that apply to your variant. The supported systems are:

• Solaris 
• Linux - (NB Linux section below has distribution specific notes on Fedora, Debian and RHEL5/CentOS5.2 as well as generic Linux instructions) 
• FreeBSD7

N.B.  When following the download and installation notes below, KE recommends using MapServer version 5.2 or above, however please do not use versions 5.4.1 or 5.4.2 due to an issue they have with spatial querying.

WMS Layers

You may want to include WMS layer support in the mapper. WMS layers are map layers provided dynamically by a WMS service rather than as layers or images stored on your system. There are many WMS layers you can use (e.g. see http://wms-sites.com/ or http://www.ogc-services.net/)

To use WMS layers in the mapper, the web server hosting the EMu Mapper needs to be allowed to contact and retrieve data from a WMS server. This is done using an HTTP request from the Web Server so requires the webserver to be able to resolve host names and initiate calls outbound to port 80 on remote servers. If WMS is not wanted (or the security setup of the web server precludes it) you can remove the need for installing the 'curl' packages and also the configure option '--with-wms-client' from the mapserver build instructions below. 

Solaris

The notes below apply to all version of Solaris for SPARC and x86 based hardware. They assume you have installed and configured Apache and PHP.

A number of packages may need to be installed in order to have MapServer operational. In particular the following packages are required:

• wget (SUNWwgetu or SMCwget)
• libiconv (SMCliconv)
• jpeg (SUNWjpg-devel or SMCjpeg)
• libpng (SUNWpng-devel or SMClibpng)
• freetype (SUNWfreetype2 or SMCftype)
• zlib (SUNWzlib or SMCzlib)
• gd (SMCgd)
• libproj
• GDAL
• mapserver
• Also if you want WMS support: curl (SMCcurl), libintl (SMClintl) and libidn (SMClibidn), openssl (SMCossl)  

Before starting the install, determine what packages are already available on your system. Enter pkginfo to get a list of installed packages and search for the ones listed above (the package names are enclosed within brackets). You can also check for an individual package by doing:

pkginfo PACKAGENAME
e.g.: "pkginfo SMCwget"

Where a package is not installed you will need either to load it from the Solaris installation disks or fetch it from www.sunfreeware.com. The notes below assume that wget, libiconv, jpeg, libpng, freetype, zlib and gd are already installed on the machine.

Many of the packages install into /usr/local/lib. It is important that this directory is included in the list of directories searched for dynamic libraries. To confirm this:

1. Log in as root on the web server machine.
2. Enter crle
   The list of directories searched is printed.
3. Confirm that /usr/local/lib is included.
4. If it is not included, enter crle  -l  currentpath:/usr/local/lib where currentpath is the existing directory list.
5. Log out.

Development environment

Make sure that a C compiler and associated tools are installed on the system and that paths are appropriately set to access these tools. Your path setting will depend on the development tools installed (and on which ones you want to use). A typical path on Solaris 10 may be something like:

PATH=/usr/sbin:/usr/bin:/usr/local/bin:/usr/sfw/bin:/usr/ccs/bin

This will typically pick up the GNu C and C++ compiler, both make and gmake, an appropriate ar etc. However you may need to adjust this as required.

libproj

For Solaris 10, the Proj.4 libraries can be simply installed as a package available from sunfreeware (SMCproj) and may be available for other Solaris environments.

If you cannot find a suitable Proj.4 package for your Solaris system you will need to build it using instructions below:  

1. Log in as root on the web server machine.
2. Make sure the make command is in your path by typing which make
   You may need to enter PATH=$PATH:/usr/ccs/bin on the command line.
3. Make sure the C compiler is in your path by typing which cc or which gcc. If necessary adjust the path to provide access.
4. Enter cd  /tmp
5. Start your web browser and navigate to http://trac.osgeo.org/proj/
6. Navigate to the latest source release and write down the URL, e.g. ftp://ftp.remotesensing.org/proj/proj-4.6.1.tar.gz
7. Enter wget  urltosrc
   The source will be downloaded into /tmp.
8. Enter  gunzip  <  proj-version.tar.gz  |  tar  xvf  -
9. Enter cd  proj-version
10. Enter ./configure
11. Enter make
    A potential source of failure at this point can occur if a mixture of Solaris and GNU development tools are used together. Ensure your path accesses the appropriate tools - either all Solaris or all GNU but not both. If you change the path, ensure you re-run the ./configure step.
12. Enter make  install
13. Enter cd  /tmp
14. Stay logged in for the next part.

GDAL 

It is recommended GDAL be built using GNU make (or gmake) and gcc/g++.

1. Start your web browser and navigate to http://www.gdal.org/
2. Navigate to the latest source release and write down the URL, e.g. ftp://ftp.remotesensing.org/gdal/gdal-1.5.2.tar.gz
3. Enter wget  urltosrc
   The source will be downloaded into /tmp.
4. Enter  gunzip  <  gdal-version.tar.gz  |  tar  xvf  -
5. Enter cd  gdal-version
6. Enter ./configure  --without-libtool
7. Enter gmake
8. Enter gmake  install
9. Enter cd  /tmp
10. Stay logged in for the next part.

mapserver

1. Start your web browser and navigate to http://mapserver.gis.umn.edu/
2. Navigate to the latest source release and write down the URL, e.g. http://download.osgeo.org/mapserver/mapserver-5.2.0.tar.gz
3. Enter wget  urltosrc
   The source will be downloaded into /tmp.
4. Enter  gunzip  <  mapserver-version.tar.gz  |  tar  xvf  -
5. Enter cd  mapserver-version
6. The paths below depend on the packages installed. In particular freetype is in /usr/local if the sunfreeware version (SMCftype) is installed.
   Enter:
   ./configure \
       --with-gd=/usr/local/ \
       --with-jpeg \
        --with-libiconv=/usr/local \
       --with-freetype=/usr/sfw/bin/freetype-config \
       --with-php=/usr/local/include/php \
       --with-proj=/usr/local \
       --with-gdal=/usr/local/bin/gdal-config \
       --with-wmsclient \
       --with-curl-config=/usr/local/bin/curl-config \
       --with-threads
   (NB you can drop the "--with-wmsclient" and "--with-curl-config=/usr/local/bin/curl-config" options if you don't want WMS support).
7. Enter make
8. Enter cd  mapscript/php3
9. Check all required libraries are installed by doing:
   ldd php_mapscript.so
   and checking all listed libraries have a path (you can grep for 'file not found' to find missing items).
10. Enter php  -i  |  egrep  extension_dir
    The command above will print out the location in which the PHP extensions are installed.
11. Enter cp  php_mapscript.so  extension_dir
12. Enter php  -i  |  egrep  php.ini
13. The path to the PHP initialisation file will be printed. Edit the file and look for the line:
    ;extension=php_sockets.dll
    and below it add the line:
    extension=php_mapscript.so
14. Restart Apache so that the extension is loaded.
15. Enter php  -m
16. Verify that MapScript and sockets are installed.
17. Log out.

The mapserver installation is now complete. If required, source downloaded to /tmp can now be removed.  

Generic Linux

Please also check specific distribution notes further below for Fedora, Debian and RHEL5/CentOS5.2 prior to installing.

A number of components may need to be installed in order to have MapServer operational. In particular the following packages are required:

•  wget (wget)
•  libjpeg (libjpeg-devel)
•  libpng (libpng-devel)
•  freetype (libfreetype-devel)
•  zlib (zlib-devel)
•  gd (gd-devel)

Before starting the install, determine what packages are already available on your system. Enter rpm -qa to get a list of installed packages and search for the ones listed above (the package names are enclosed within brackets). Where a package is not installed you will need to install it from your installation disks or from a suitable internet source for your linux distribution.  Note that some of the required packages are the development version, not the standard version that may already be installed by default.  If you only have the standard package installed you will need to install the development version.

Typically the install of any missing packages would require:

rpm

rpm  -i  http://site/path_to_rpms/gd-devel-2.0.33-6.2.i386.rpm

yum

yum install gd-devel

apt

apt-get install gd-devel

The notes below assume that wget, jpeg-devel, libpng-devel, freetype-devel, zlib-devel and libgd-devel are already installed on the machine. You will now need to build and install libproj, GDAL and mapserver.

libproj 

1. Log in as root on the web server machine.
2. Enter cd  /tmp
3. Start your web browser and navigate to http://trac.osgeo.org/proj/
4. Navigate to the latest source release and write down the URL, e.g. ftp://ftp.remotesensing.org/proj/proj-4.6.1.tar.gz
5. Enter wget  urltosrc
   The source will be downloaded into /tmp.
6. Enter  gunzip  <  proj-version.tar.gz  |  tar  xvf  -
7. Enter cd  proj-version
8. Enter ./configure
9. Enter make
10. Enter make  install
11. Enter cd  /tmp
12. Stay logged in for the next part.

GDAL 

1. Start your web browser and navigate to http://www.gdal.org/
2. Navigate to the latest source release and write down the URL, e.g. ftp://ftp.remotesensing.org/gdal/gdal-1.5.2.tar.gz
3. Enter wget  urltosrc
   The source will be downloaded into /tmp.
4. Enter  gunzip  <  gdal-version.tar.gz  |  tar  xvf  -
5. Enter cd  gdal-version
6. Enter:
   ./configure  --without-ogdi  \
             --without-python \
             --without-geos \
             --without-pg \
             --without-odbc \
             --with-png=internal \
             --with-jpeg=internal \
             --with-libz=internal \
             --with-static-proj4=/usr/local/lib
7. Enter make
8. Enter make  install
9. Enter cd  /tmp
10. Stay logged in for the next part. 

mapserver 

1. Start your web browser and navigate to http://mapserver.gis.umn.edu/
2. Navigate to the latest source release and write down the URL, e.g. http://download.osgeo.org/mapserver/mapserver-5.2.0.tar.gz
3. Enter wget  urltosrc
   The source will be downloaded into /tmp.
4. Enter  gunzip  <  mapserver-version.tar.gz  |  tar  xvf  -
5. Enter cd  mapserver-version
6. The paths below depend on the packages installed. Enter:
   ./configure  --with-gd=/usr/local \
             --with-freetype=/usr/bin/freetype-config \
             --without-tiff \
   --with-wmsclient \
             --with-gdal=/usr/local/bin/gdal-config \
             --with-php=/usr/include/php \
             --with-proj=/usr/local
   (NB you can drop the "--with-wmsclient" option if you don't want WMS support).
7. Enter make
8. Enter cd  mapscript/php3
9. Enter ldd  php_mapscript.so
   Check that all libraries have been resolved correctly.
   If not, /usr/local/lib must be added to the default library path.
   
   If only /etc/ld.so.conf exists (no /etc/ld.so.conf.d) :
   1. Enter vi  /etc/ld.so.conf
   2. Add /usr/local/lib to the end of the file.
   3. Enter ldconfig
   
   If /etc/ld.so.conf.d exists:
   1. Enter vi  /etc/ld.so.conf.d/mapscript.conf
   2. Add a single line containing /usr/local/lib
   3. Enter ldconfig
   
   
10. Enter php-config  -extension-dir
11. The command above will print out the location in which the PHP extensions are installed.
12. Enter cp  php_mapscript.so  extension_dir
13. Enter php  -i  |  egrep  php.ini
    The path to the PHP initialisation file will be printed.
14. Edit the file and look for the line:
    ;extension=php_sockets.dll
    and below it add the line:
    extension=php_mapscript.so
15. Restart Apache so that the extension is loaded.
16. Enter php  -m
17. Verify that MapScript and sockets are installed.
18. Log out.

The MapServer installation is now complete. If required, source downloaded to /tmp can now be removed. 

Distribution Specific Note

RHEL 5, CentOS 5.2

RHEL (and CentOS) do not by default install the development components of a number of libraries used by mapserver. The instructions below describe the RHEL and CentOS specific process of building mapserver.

1. Install gcc

If not installed, install the gcc compiler:

yum install gcc gcc-c++ autoconf automake

(or rpm -ivh gcc)

2. Install development versions of libraries/packages

Using yum: 

    yum install freetype-devel

    yum install libpng-devel

    yum install libjpeg-devel

    yum install gd-devel

    yum install curl-devel

    yum install php-devel

    yum install php-gd

Alternatively using rpm: 

    rpm -ivh freetype-devel.rpm

    rpm -ivh libpng-devel.rpm

    rpm -ivh libjpeg-devel.rpm

    rpm -ivh gd-devel.rpm

    rpm -ivh curl-devel.rpm

    rpm -ivh php-devel.rpm

    rpm -ivh php-gd.rpm

 
NB: When using rpm it is necessary to download the package first before it can be installed (or specify the full URL to the package so it can be downloaded).

3. Build libproj as per generic notes above

4. Build GDAL as per generic notes above

5. mapserver

1. Start your web browser and navigate to http://mapserver.gis.umn.edu/
2. Navigate to the latest source release and write down the URL, e.g. http://download.osgeo.org/mapserver/mapserver-5.2.0.tar.gz.
3. Enter wget  urltosrc
   The source will be downloaded into /tmp.
4. Enter  gunzip  <  mapserver-version.tar.gz  |  tar  xvf  -
5. Enter cd  mapserver-version
6. Enter:./configure \
       --with-gd=/usr \
       --with-freetype=/usr/lib \
       --with-png=/usr/lib \
       --without-tiff \
       --with-gdal=/usr/local/bin/gdal-config \
       --with-php=/usr/include/php \
       --with-wmsclient \
       --with-proj=/usr/local
   (NB you can drop the "--with-wmsclient" option if you don't want WMS support).
7. Enter make
8. Enter cp mapscript/php3/php_mapscript.so /usr/lib/php/modules/
9. Create and edit the file /etc/php.d/mapscript.ini
   Enter the 2 lines:  
   ; Enable mapscript extension module
   extension=php_mapscript.so
10. Create and edit the file  /etc/ld.so.conf.d/mapscript.conf
    Add a single line:
    /usr/local/lib 
11. Enter ldconfig
12. Restart Apache so that the extension is loaded.
13. Enter php  -m
14. Verify that MapScript and sockets are installed.
15. Log out. 

6. SE Linux 

The webservice system (and hence the mapper) creates files in a temporary cache directory and so will be prevented from working when running SE Linux under the 'enforcing' state if using the default RHEL/CentOS/Fedora SE Linux settings. A suggested policy that will allow the Mapper to run is:
allow httpd_t devpts_t:chr_file ioctl;
allow httpd_t port_t:tcp_socket name_connect;
allow httpd_t user_home_t:dir { add_name getattr read remove_name search write };
allow httpd_t user_home_t:file { append create getattr ioctl lock read setattr unlink write }; 

Fedora

1. Install any missing libraries/components etc.  

e.g.:

yum install php-devel php-gd proj-devel curl-devel libjpeg-devel libpng-devel zlib-devel

NB libproj can be installed in FC as a package - no need to download and compile.

2. Install gdal from source 

wget http://download.osgeo.org/gdal/gdal-1.5.2.tar.gz

./configure

make

make install

3. Build Mapserver

Use the following build options:

./configure \
    --with-proj=/usr \
    --with-gdal=/usr/local/bin/gdal-config \
    --without-tiff \
    --with-gd=/usr \
    --with-libiconv=/usr \
    --with-jpeg=/usr \
    --with-freetype=/usr/bin/freetype-config \

    --with-php=/usr \

    --with-wmsclient \

    --with-png=/usr 

(NB you can drop the "--with-wmsclient" option if you don't want WMS support).

4. Install php module

cp mapscript/php3/php_mapscript.so /usr/lib/php/modules/

Create file: /etc/php.d/mapscript.ini containing the single line:

extension=php_mapscript.so

NB if you enter extension=php_mapscript.so in php.ini instead of in the php.d directory, you may have mapscript not being loaded because the gd libraries it is built with differ from the ones used by php. A typical error in this case looks like:

"PHP Warning: Unknown(): Unable to load dynamic library

php_mapscript.so. undefined symbol: php_gd_gdImageCopy in Unknown on line 0" 

5. Restart Apache 

6. SE Linux  

See RHEL5/CentOS5.2 SE Linux notes above about SE Linux policies. 

Debian

Notes below are if you are using Debian 'Etch'.

Installing mapscript on Etch can be quite trivial because there is a php5-mapscript package that can be installed by running:

apt-get install php5-mapscript 

By installing this package you can skip the building of proj.4, gdal, mapscript etc. altogether. It is however an older release of mapserver (version 4.10.0) so you may decide to install by source if you require the latest features. 

Debian Notes if you decide not to use the php5-mapscript package 

The basic procedure is to follow the generic Linux notes above however be aware: 

1. When installing libgd package, make sure you install libgd2-xpm-dev NOT  libgd-dev.
2. If wanting WMS functionality, you should install the libcurl3-dev package.
3. For Debian 'Etch', you do not need to build Proj.4 library or GDAL from source as you can get and install these from packages using apt:
   apt-get install proj
   apt-get install libgdal1-1.3.2-dev
   However be aware the GDAL package will install a number of additional packages that you may not want. You can of course install GDAL from source as per the Generic Linux notes above to avoid this.
4. The following configure options should be appropriate for a standard Debian Etch distribution:
   ./configure --with-gd=/usr \
       --with-freetype=/usr/bin/freetype-config \
       --with-jpeg=/usr \
       --with-png=/usr \
       --without-tiff \
       --without-xpm \
       --with-wmsclient \
       --with-gdal=/usr/local/bin/gdal-config \
       --with-php=/usr/include/php5 \
       --with-proj=/usr \
       --with-httpd=/usr/sbin/apache2
   
   If you don't want WMS support you can remove the "--with-wmsclient" option.

FreeBSD

These notes document how to build Mapserver on FreeBSD 7.0 using a later Mapserver version if the version in FreeBSD ports is not suitable (when last checked - 28 July 2008 - the ports mapserver version was still only 4.4.1 which is not suitable for Web Maps). The notes below assume Apache and PHP5 installed from ports and working properly. You may already have some components installed or may require some extras. If so you may need to install extra bits typically from the FreeBSD ports collection. Those missing should become obvious when configuring and compiling Mapserver as it will complain about them not being found.

1. Install proj4 from ports

As root:

cd /usr/ports/misc/proj4

make install

make clean

 2. Install gdal from ports

As root:

cd /usr/ports/graphics/gdal

make -DNOPORTDOCS=1 install

make clean

Note: The -DNOPORTDOCS directive above is not strictly required but is used to reduce the number of additional packages that are installed using the default port build. Without this argument you will install a large number of other packages, including DOxygen (a documentation system) which requires a lot of additional components (including CUPS, tmake, the Qt libraries, etc.). These are for documentation not GDAL functionality and may not be wanted (or may make building more difficult if there are problems building the dependent packages).

3. Install libgd  

As root:

cd /usr/ports/graphics/gd

make install

make clean 

4. Install curl 

(Because we are going to build mapserver with WMS client capability): 

As root:

cd /usr/ports/ftp/curl
make install
make clean  

5. If not available on the system, install wget from ports 

As root:

cd /usr/ports/ftp/wget
make install
make clean

6. Building Mapserver 

Make a temporary work directory and change to it.

mkdir ~/work
cd ~/work

wget 'http://download.osgeo.org/mapserver/mapserver-5.2.0.tar.gz'

(obviously adjust the version as required).

tar -zxvf mapserver-5.2.0.tar.gz
cd mapserver-5.2.0
./configure \
    --with-proj=/usr/local/ \
    --with-gdal=/usr/local/bin/gdal-config \
    --without-tiff \
    --with-gd=/usr/local \
    --with-libiconv=/usr/local \
    --with-jpeg=/usr/local \
    --with-freetype=/usr/local/bin/freetype-config \
    --with-php=/usr/local/include/php \
    --with-wmsclient \
    -with-png=/usr/local

Check it configures OK, in particular gives:

    Proj.4 support:    -DUSE_PROJ

    GDAL support:      -DUSE_GDAL

    PHP MapScript:     yes

gmake 

***NB*** NOT FreeBSD make! - it is necessary to use gnu make (i.e. gmake)  

7. Install the mapscript module 

As root:

cp mapscript/php/php_mapscript.so `php-config --extension-dir`

Edit /usr/local/etc/php/extension.ini and add:

"extension=php_mapscript.so"

Confirm it is installed by doing php -m and look for MapScript.  

8. Restart apache