.. index::
   pair: Unix; Installation

.. _unix:

*****************************************************************************
 Compiling on Unix
*****************************************************************************

:Author: Howard Butler
:Contact: hobu.inc at gmail.com
:Author: Thomas Bonfort
:Contact: thomas.bonfort at gmail.com
:Author: Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com
:Last Updated: 2019-04-16

.. contents:: Table of Contents
    :depth: 2
    :backlinks: top


=============================================================================
 Introduction
=============================================================================

The University of Minnesota's MapServer is an open-source and freely 
available map rendering engine for the web. Due to its open-source nature, 
it can be compiled on a wide variety of platforms and operating systems. 
We will focus on how to obtain, compile and install MapServer on UNIX-like 
platforms.

.. note:: 

   Detailed configuration options are maintained in the `INSTALL.CMAKE`_
   file packaged at the root of the source directory:

You might also check the `MapServerCompilation`_ wiki page for
additional information.

=============================================================================
 Obtaining the necessary software
=============================================================================

You can obtain the MapServer source code as well as the demo package from the 
:ref:`download` section.

You can also get the latest MapServer source code from :ref:`git`.

-----------------------------------------------------------------------------
 Required External Libraries
-----------------------------------------------------------------------------

* `libpng`_: libpng should be on your system by default.  Versions
  back to 1.2.7 should work.

* `freetype`_: Version 2.x or above is required.

* `libjpeg`_: libjpeg allows MapServer to render 
  images in JPEG format.  A sufficient version should be installed by 
  default on your system (probably version 6b from 1998).

  .. warning::
        
        Direct JPEG support was deprecated in MapServer 5.8+, and you
        should now depend on GDAL for raster read support in
        MapServer. JPEG support is however still required for
        producing (i.e. writing) images.
  
* `zlib`_: Zlib should be on your system by default.  Though not used
  directly by mapserver, it's a mandatory dependency of libpng.

-----------------------------------------------------------------------------
 Highly Recommended Libraries
-----------------------------------------------------------------------------

* `libproj`_: libproj provides projection support for MapServer.
  Version 4.4.6 or greater is required.

* `libcurl`_: libcurl is the foundation of OGC (WFS/WMS/WCS) client
  and server support.  Version 7.10 or greater is required.
* `OGR`_: OGR provides access to a lot of vector formats.
* `GDAL <http://www.gdal.org/>`__: GDAL provides access to a lot of
  raster formats.

-----------------------------------------------------------------------------
 Optional External Libraries
-----------------------------------------------------------------------------

* `GEOS`_: GEOS allows MapServer to do 
  spatial predicate and algebra operations (within, touches, etc & union, 
  difference, intersection). 

  .. versionadded:: 4.10
  
* `libxml`_: libxml is required to use :ref:`OGC
  SOS <sos_server>` support in MapServer
  
  .. versionadded:: 4.10
  
* `Oracle Spatial OCI`_: The client libraries for your platform are
  available for download from Oracle's website.  Ideally, your client
  library matches the database you are querying from, but this is not
  a hard requirement.
  
* `libpq`_: libpq is required to support the use of PostGIS geometries
  within the PostgreSQL database.  Ideally, your client library
  matches the database you are querying from.
  
* `giflib`_: libgif / `libgif`_ is is used for reading GIF files used
  as PIXMAP symbols.

* `FastCGI`_: FastCGI is a popular protocol for interfacing MapServer
  with various web servers.  You will need to install the development
  package.
  More details on how to use this feature in MapServer is here :ref:`fastcgi`.
  On Ubuntu, that would be::

      $ apt-get -y install libfcgi-dev

* `Cairo (SVG, PDF) support`_: This library is required to produce PDF
  and SVG outputs.  If you're on an ubuntu system, it can be installed
  with "apt-get install -y libcairo2-dev"

* `KML support`_: This renderer is has no external dependency.

.. index::
   single: HarfBuzz

.. index::
   single: FriBidi

* `HarfBuzz`_: Support complex script shaping (to simplify: the tool
  that will insert ligatures between characters).  Harfbuzz algorithms
  will be applied on text strings that have been determined to not be
  latin (i.e. the slowdown induced by harfbuzz is limited to those
  languages that actually require shaping).  Requires `FriBidi`_.

  .. seealso::

    :ref:`rfc98`


  .. versionadded:: 7.0

* MySQL: Support joining with MySQL (the WITH_MYSQL option).

-----------------------------------------------------------------------------
 Optional Features
-----------------------------------------------------------------------------

* `Cairo SVG parser support`_: The WITH_SVGCAIRO option is part of a
  proposal to improve SVG support.  Using this feature requires
  installing the libsvg-cairo library available here:
  http://cairographics.org/snapshots/ .  You will need to compile and
  install cairo, libsvg, and libsvg-cairo.

* SVG support can be enabled either through the unmaintained libsvg /
  libsvg-cairo combo, or through librsvg (the WITH_RSVG option) at the
  cost of more dependencies. Use librsvg if your distro provides a
  package for it, or fall back to libsvgcairo if the cost of compiling
  the librsvg dependencies is too important.

=============================================================================
Anti-Grain Geometry Support
=============================================================================
Since version 5.0 MapServer supports the AGG rendering backend.
MapServer 5.6+ embeds it directly in the source tree and you do not have to 
do anything special to have support for it.

=============================================================================
 OGC Support
=============================================================================
MapServer provides support for many `OGC`_ specifications.  For an
overview, see :ref:`ogc_support`.

-----------------------------------------------------------------------------
 WMS support
-----------------------------------------------------------------------------

WMS Server
-------------------
Support for `WMS server` is automatically enabled.

You can check it by looking for the following in your configure
output::

  --   * WMS SERVER: ENABLED

If, for some reason you don't want WMS support, you can force it off 
using "-DWITH_WMS=OFF".

More information on using this feature is available in :ref:`wms_server`.

WMS Client
-------------------
Cascading is also supported. This allows mapserver to transparently 
fetch remote layers over WMS, basically acting like a client, and combine 
them with other layers to generate the final map.

In order to enable this feature, you will need to pass the
WITH_CLIENT_WMS option to the configure script. MapServer will
automatically look for libcurl, which is also required.

To verify that this feature is enabled, check the configure output
for::

  --   * WMS CLIENT: ENABLED

.. note::

    This feature is disabled by default, you have to specifically
    request it.

More information on using this feature is available in :ref:`wms_client`.

-----------------------------------------------------------------------------
 WFS support
-----------------------------------------------------------------------------

WFS Server
-------------------
Support for `WFS server` is enabled by default. OGR and PROJ.4 support
is required.

To verify that this feature is enabled, check the configure output
for::

  --   * WFS SERVER: ENABLED

If, for some reason you don't want WFS support, you can force it off 
using "-DWITH_WFS=OFF".

More information on using this feature is available in 
:ref:`wfs_server`.

WFS Client
-------------------
MapServer can also act as a WFS client.  This effectively means that
MapServer reads it's data from a remote server's WFS output and
renders it into a map, just like it would when reading data from a
shapefile.

In order to enable this feature, you will need to make sure you have
OGR (built with Xerces support) and PROJ.4 support, and pass the
WITH_CLIENT_WFS option to your configure script.  MapServer will
automatically look for libcurl, which is also required.

To verify that this feature is enabled, check the configure output
for::

  --   * WFS CLIENT: ENABLED

.. note::
  
    This feature is disabled by default, you have to specifically
    request it.

More information on using this feature is available in :ref:`wfs_client`.

WCS Server
-------------------
Support for `WCS server` is enabled by default.  WCS must be compiled
against certain libraries.  More information on this service is
available in :ref:`wcs_server`.

To verify that this feature is enabled, check the configure output
for::

  --   * WCS SERVER: ENABLED

If, for some reason you don't want WCS support, you can force it off 
using "-DWITH_WCS=OFF".

SOS Server
-------------------
Support for SOS is enabled by using the WITH_SOS option.  More
information on this service is available in :ref:`sos_server`.

To verify that this feature is enabled, check the configure output
for::

  --   * SOS SERVER: ENABLED

.. note::
  
    This feature is disabled by default, you have to specifically
    request it.

=============================================================================
 Spatial Warehousing
=============================================================================
MapServer can use a wide variety of sources of data input. One of the 
solutions growing in popularity is to use spatially enabled databases to 
store data, and to use them directly to draw maps for the web.

Here you will find out how to enable mapserver to talk to one of these 
products. Please refer to the MapFile reference for more details on how to 
use these. This section only details how to compile MapServer for their use.

-----------------------------------------------------------------------------
 PostGIS
-----------------------------------------------------------------------------
`PostGIS`_ adds support for geographic objects to the `PostgreSQL`_
object-relational database. In effect, PostGIS "spatially enables" the
PostgreSQL server, allowing it to be used as a backend spatial
database for geographic information systems (GIS), much like ESRI's
SDE or Oracle's Spatial extension.  PostGIS is included in many
distributions' packaging system, but you can also roll your own if
needed.

MapServer can use PostGIS as a data source. PostGIS support is enabled
by default.

To verify that this feature is enabled, check the configure output
for::

  --   * POSTGIS: /usr/local/pgsql/lib/libpq.so

If, for some reason you don't want PostGIS support, you can force it
off using "-DWITH_POSTGIS=OFF".  To help cmake find your PostGIS
installation, you can use the CMAKE_PREFIX_PATH option
(for instance "-DCMAKE_PREFIX_PATH=/usr/local/pgsql").

-----------------------------------------------------------------------------
 Oracle Spatial
-----------------------------------------------------------------------------

Oracle's Spatial is also supported by MapServer.  In order to connect
to it, you will need to compile MapServer against the Oracle libraries
by using the WITH_ORACLESPATIAL option.  You will very likely need an
ORACLE_HOME environment variable set to have it configure things
correctly.

To verify that this feature is enabled, check the configure output
for::

  --   * Oracle Spatial: <path to oracle spatial shared library>

=============================================================================
 Compiling
=============================================================================
First prepare the ground by making sure all of your required and/or 
recommended libraries are installed before attempting to compile MapServer.  
This will make your life much less complicated ;).  Here is the order that I 
usually use:

1. Compile GDAL/OGR.  Describing how to compile GDAL/OGR is beyond the scope
   of this document.  If you have requirements for lots of different formats,
   make sure to install those libraries first.  I often find that building 
   up a GDAL/OGR library often takes as long as compiling MapServer itself!   

2. Compile PROJ.4.  PROJ.4 is a straight-forward configure/make/make install 
   library.  
   
3. Compile libcurl.  libcurl is a straight-forward configure/make/make
   install library.  This library is only used along with other
   features, so "--with-curl-config" won't do anything unless
   something like "--with-wmsclient" or "--with-wfsclient" is also
   selected.

   .. note::

        If you want to configure MapServer to use SSL when accessing a
        WMS/WFS server libcurl must be configured / compiled with the
        "--with-ssl" option.  Details about how to set this up is
        available in :ref:`wxs_secure`.

4. Compile/install optional libraries.  These might include PostGIS,
   Oracle Spatial, AGG, Ming, PDFlib, or MyGIS.  Mix and match as you need
   them.

5. Unpack the MapServer tarball and cd into the mapserver directory::
   
      $ tar -zxvf mapserver-X.Y.Z.tar.gz

6. Create the build directory and configure your environment.

   Create the build directory::

      $ cd mapserver-X.Y.Z
      $ mkdir build
      $ cd build

   Configure your environment using "cmake" (this is an example)::

      $ cmake -DCMAKE_INSTALL_PREFIX=/opt \
              -DCMAKE_PREFIX_PATH=/usr/local/pgsql/91:/usr/local:/opt \
              -DWITH_CLIENT_WFS=ON \
              -DWITH_CLIENT_WMS=ON \
              -DWITH_CURL=ON \
              -DWITH_SOS=ON \
              -DWITH_PHP=ON \
              -DWITH_PERL=ON \
              -DWITH_RUBY=ON \
              -DWITH_JAVA=ON \
              -DWITH_CSHARP=ON \
              -DWITH_PYTHON=ON \
              -DWITH_SVGCAIRO=ON \
              -DWITH_ORACLESPATIAL=ON \
              -DWITH_MSSQL2008=ON \
              ../ >../configure.out.txt

   The following options are enabled by default (version 7.0:
   WITH_PROJ, WITH_WMS, WITH_FRIBIDI, WITH_HARFBUZZ, WITH_ICONV,
   WITH_CAIRO, WITH_FCGI, WITH_GEOS, WITH_POSTGIS, WITH_GDAL,
   WITH_OGR, WITH_WFS, WITH_WCS, WITH_LIBXML2, WITH_GIF.

   If you want to also build a static version of the library, the
   BUILD_STATIC and LINK_STATIC_LIBMAPSERVER options can be used,

   There are a number of other options available.  For an up-to-date
   list of available cmake options, refer to the CMakeLists.txt.

   It can be a good idea to place the configuration commands in a file
   and change its mode to executable (+x) to save typing and have a
   record of how MapServer was configured.                      

7. Now that you have configured your build options and selected all the 
   libraries you wish mapserver to use, you're ready to compile the 
   source code.
   
   This is actually quite simple, just execute "make"::
   
     $ make


8. Install the MapServer libraries::

     # make install
   
   To make sure all went well, look for the file called *mapserv*::
   
     $ ls -al mapserv
     -rwxr-xr-x  1 user user 13745 mars  11 17:45 mapserv
   
   A simple test is to try and run it::
   
     $ ./mapserv
     This script can only be used to decode form results and
     should be initiated as a CGI process via a httpd server.

   The message above is perfectly normal, and means exactly what it says. 
   If you get anything else, something went terribly wrong.

=============================================================================
 Installation
=============================================================================
-----------------------------------------------------------------------------
 MapServer binary
-----------------------------------------------------------------------------
The MapServer program itself consists of only one file, the "mapserv" binary
executable. This is a CGI executable, meant to be called and run by your
web server.

In this section, we will assume you are running Apache under its default 
directory structure in /usr/local/apache2. You may need to have privileges
to edit your httpd.conf (the main apache configuration file), or have 
someone (such as your webmaster) help you with the configuration details.

If you don't have apache installed, and you want apache, php, fastcgi,
etc, that might look something like this::

  $ apt-get install -y apache2 apache2-mpm-worker libapache2-mod-fastcgi
  $ a2enmod actions fastcgi alias
  $ apt-get install libapache2-mod-php5 php5-common php5-cli php5-fpm php5

The main goal is to get the "mapserv" binary installed in a publicly 
accessible directory that is configured to run CGI programs and scripts.

1. Locate your cgi-bin directory.  Under a default configuration, the
   CGI directory is "/usr/local/apache2/cgi-bin" (RedHat:
   "/home/httpd/cgi-bin", Debian: "/usr/lib/cgi-bin").  If you're
   using apache, there should be a ScriptAlias directive in your
   http.conf, or default site, something like::

     $ cat /etc/apache2/sites-available/default | grep 'cgi-bin'
     ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

2. Locate the installation path of your freshly compiled mapserv
   executable.  This is shown when you run "make install",
   something like this::

     -- Installing: /usr/local/bin/mapserv
     -- Set runtime path of "/usr/local/bin/mapserv" to
           "/usr/local/lib:/usr/local/pgsql/91/lib"

3. You'll want to setup a symlink to that executable from your cgi-bin
   directory::

     # ln -s /usr/local/bin/mapserv /usr/lib/cgi-bin/mapserv

   .. warning::

     Make sure you are linking against the installed mapserv file (after
     running 'make install') and NOT against where it was compiled in
     your source tree.


Testing your new Install
------------------------

Placing the mapserv file in this directory makes it accessible by the
following URL:
"http://yourhostname.com/cgi-bin/mapserv". When accessing this URL through your 
web client, you should expect the following output if all has worked well: 
"No query information to decode. QUERY_STRING is set, but empty." If you get 
this message, you're done installing MapServer.

-----------------------------------------------------------------------------
 Common problems
-----------------------------------------------------------------------------
File permissions
-------------------
The most common problem one is likely to encounter when attempting to 
install the binary are permissions issues:

*  You do not have write permissions into your web server's CGI Directory. 
   Ask your webmaster to install the file for you.
*  The web server gives you a "403 Permission denied" error. Make sure the 
   user the web server runs as (usually "nobody") has execute permission on 
   the binary executable. Making the file world executable is perfectly 
   fine and safe:
   ::
   
      $ chmod o+x mapserv

Apache errors
-------------------
You may receive a few different type of errors as well if your web 
server configuration isn't right: 

*  500 Internal server error: This is a fairly generic error message. 
   All it basically tells you is that the web server was unsuccessful 
   in running the program. You will have to consult the web server's error 
   log to find out more, and may need to enlist the help of your 
   webmaster/system administrator.  The apache docs also have pointers
   on `setting up cgi-bin`_.

     ::
        Check your server logs
        $ tail /var/log/apache2/error.log


-----------------------------------------------------------------------------
 Where to go once you've got it compiled
-----------------------------------------------------------------------------
The :ref:`introduction` document provides excellent coverage of getting started 
with MapServer.  

.. _`post to mapserver-users`: http://article.gmane.org/gmane.comp.gis.mapserver.user/17766
.. _`INSTALL.CMAKE`: https://github.com/mapserver/mapserver/blob/master/INSTALL.CMAKE
.. _`MapServerCompilation`: http://trac.osgeo.org/mapserver/wiki/MapServerCompilation
.. _`libpng`: http://www.libpng.org/pub/png/libpng.html
.. _`freetype`: http://www.freetype.org/
.. _`libjpeg`: http://www.ijg.org/
.. _`zlib`: http://www.gzip.org/zlib
.. _`libproj`: http://trac.osgeo.org/proj/
.. _`libcurl`: http://curl.haxx.se/libcurl/
.. _`OGR`: http://www.gdal.org/
.. _`GDAL`: http://www.gdal.org/
.. _`GEOS`: http://trac.osgeo.org/geos/
.. _`libxml`: http://xmlsoft.org
.. _`Oracle Spatial OCI`: http://www.oracle.com/technology/products/spatial/index.html
.. _`libpq`: http://www.postgresql.org/
.. _`giflib`: http://giflib.sourceforge.net/
.. _`FastCGI`: http://www.fastcgi.com
.. _`Cairo (SVG, PDF) support`: http://cairographics.org/
.. _`KML support`: http://mapserver.org/output/kml_output.html
.. _`Cairo SVG parser support`: http://mapserver.org/development/rfc/ms-rfc-73.html
.. _`OGC`: http://www.opengeospatial.org
.. _`PostGIS`: http://postgis.net
.. _`setting up cgi-bin`: http://httpd.apache.org/docs/2.2/howto/cgi.html
.. _`PostgreSQL`: http://www.postgresql.org
.. _`libgif`: https://launchpad.net/ubuntu/precise/+package/libgif-dev
.. _`HarfBuzz`: http://freedesktop.org/wiki/Software/HarfBuzz
.. _`FriBidi`: http://fribidi.org/
