Building and Configure MapGuide Open Source on Linux

Building and Configuring on Linux

Building MapGuide on Linux

System Requirements

MapGuide Open Source requires the following components:

  • Apache HTTP Server 2.xx
  • PHP 5.2.1
  • FDO 3.2.3
  • libjpeg.so

In addition, Apache Tomcat is required if you intend to use Java Server Pages.

A complete installation of all components requires approximately 2.2 GB disk space.

MapGuide has been tested on RedHat Enterprise Linux 4 with GCC 3.4.6, and Fedora Core 6 with GCC 4.1.1.

Note: Building and installation should be done using the root user id.

Building and Installing Required Components

Note: Install and configure all required components before building MapGuide.

Building and Installing Apache, PHP, and Tomcat

MapGuide requires the Apache HTTP Server, PHP 5.2.1, and optionally Tomcat. These are bundled into a single tarball available from http://mapguide.osgeo.org. Building and installing this bundle will ensure that the components are configured properly for MapGuide.

MapGuide requires the J2SE Development Kit (JDK). To install the JDK:

To build and install Apache, PHP, and Tomcat:

  • Extract the tarball to a directory that will be used for the installation. This creates a directory named LinuxApt, containing tarballs for PHP 5.2.1, Apache HTTP Server 2.0.55 and Tomcat 5.5.12.
  • Extract the bundled components into their respective directories.
  • Run ./build_apt.sh. The following command line options are available:
    Option Description
    -prefix dir Sets the installation directory to dir. The default is /usr/local/mapguideopensource
    -port portNum Sets httpd to listen on a specific port. The default is 8008.
    -with-tomcat Builds, installs, and configures Tomcat along with httpd and PHP. Tomcat is configured to run on port 8080. By default, Tomcat is not installed.
    -help Displays a summary of these options.

build_apt.sh installs Apache httpd, PHP, and Tomcat. The default location is /usr/local/mapguideopensource/

If you use the -prefix option, the files will be installed under that directory instead.

Test Apache by connecting to port 8008 using a web browser. It should display the default Apache welcome page.

build_apt.sh is a straightforward shell script. To review the configuration options for Apache, PHP, and Tomcat, examine the shell script. If you require different options, you should begin with the MapGuide defaults before making changes.

No changes have been made to the source files for Apache, PHP, and Tomcat. They have been taken directly from their respective sites.


Building and Installing FDO 3.2

The source code for FDO Open Source is available from http://fdo.osgeo.org as a gzipped tar files:

  • fdo-3.2.3.tar.gz
  • fdoarcsde-3.2.3.tar.gz
  • fdogdal-3.2.3.tar.gz
  • fdordbms-3.2.3.tar.gz
  • fdosdf-3.2.3.tar.gz
  • fdoshp-3.2.3.tar.gz
  • fdowfs-3.2.3.tar.gz
  • fdowms-3.2.3.tar.gz

Download the source and extract to a directory that will be used for the rest of the installation.

  • Extract the source from the distribution and build FDO according to the included instructions (OpenSourceBuild_Readme.txt).
  • The installation must be carried out with the default settings.
  • Once you have installed FDO, check the execute permissions on the shared libraries in /usr/local/fdo-3.2.3/lib. Some may have been installed without execute permission. To correct the permissions, run

    chmod a+x *.so*

Download the documentation and the data for unit tests from http://fdo.osgeo.org.

Other Requirements

The libjpeg.so library is required. It is installed by default with most Linux distributions. If you do not have it, you can download the source from the Independent JPEG Group: http://www.ijg.org.

Note: You may also have to install the JPEG header files. Refer to the documentation available with the libjpeg files for instructions.

Building the MapGuide Server and Web Server Extensions

Obtaining the MapGuide Source Code

The source code for MapGuide is available from http://mapguide.osgeo.org as a gzipped tar file (mapguide-1.2.0.tar.gz). Download the source and extract to a directory that will be used for the rest of the installation. This will be referred to as SourceDir in this guide.

Building OEM Components in the MapGuide Distribution

MapGuide includes various third-party components that must be built. From SourceDir, execute the following:

./build_oem.sh

The default targets are all release.

Building and Installing the Default Configuration

To build MapGuide, change to SourceDir. For build options and help, type

./configure --help

To configure, build, and install using the default configuration, type the following commands:

  1. aclocal
  2. libtoolize --force
  3. automake --add-missing --copy
  4. autoconf
  5. ./configure (with optional build flags)
  6. make
  7. make check
  8. make install

The default build target is DEBUG.

This builds and installs both MapGuide Server and MapGuide Web Server Extensions. By default, the mgserver executable is installed in

/usr/local/mapguideopensource/server/bin

and the Web Server Extensions are installed in

/usr/local/mapguideopensource/webserverextensions/

The default directories can be changed using configuration options.

Building a Release Configuration

To build a release configuration, run the following commands from SourceDir:

  1. If you have already built MapGuide,

    make clean

  2. ./configure --enable-optimized
  3. make
  4. make install

Building Components Separately

To build only one of the components, either MapGuide Server or MapGuide Web Server Extensions, disable the additional component using either the

--enable-server=no

or

--enable-webtier=no

option. For example, to build and install just the Web Server Extensions, run the following commands from SourceDir:

  1. ./configure --enable-server=no
  2. make
  3. make install

Installing in a Different Location

By default, both MapGuide Server and MapGuide Web Server Extensions are installed in directories under /usr/local/mapguideopensource/. To change the installation directory, use the --prefix= configuration option.

For example, to install in your home directory, run the following commands from SourceDir:

  1. ./configure --prefix=$HOME
  2. make
  3. make install

Specifying FDO Locations

MapGuide requires the FDO include files and FDO libraries. If you have installed FDO in a location other than the default of /usr/local/fdo-3.2.3, you must use the --with-fdo-include and --with-fdo-lib configuration options.

./configure --with-fdo-include= IncludeDir --with-fdo-lib= LibDir

where IncludeDir is the user-defined directory containing the FDO include files, and LibDir is the directory containing the FDO libraries.

Running the Server

If MapGuide is installed in the default location. then the mgserver executable and the serverconfig.ini file are available in

/usr/local/mapmapguideopensource/server/bin

If you used the --prefix= prefix option to the configure command, the mgserver executable and serverconfig.ini are available in

prefix /server/bin

The default settings in serverconfig.ini are adequate for most users. For more information on what the settings are and what values are expected, refer to the file. It has detailed descriptions about each setting.

To start the MapGuide Server, change to the server/bin directory and execute

./mgserver.sh

Configuring MapGuide Web Server Extensions on Linux

Virtual Directory Structure

The installation procedure creates a directory structure containing the Web Extensions files. This structure is designed to be used as a virtual directory by the Apache HTTP server. By default, the files are installed in

/usr/local/mapguideopensource/webserverextensions/www

If you used the --prefix= Prefix option with the configure command, the files are installed in

Prefix /webserverextensions/www

The www/webconfig.ini file provides configuration options for the Web Server Extensions. It is configured by the installation procedure.

Note: If you are running the MapGuide Server and the Web Server Extensions on separate machines, you will need to edit webconfig.ini for each machine running Web Server Extensions. In the section [SiteConnectionProperties], set the IpAddress value to the IP address of the site server.

The directory www/TempDir is used for temporary files. The user id running the Apache httpd process must have read/write access to TempDir. For security purposes, this directory can be moved outside the virtual directory tree so it is not directly accessible via the web.

Configuring Apache HTTP Server

The installation procedure installs the Apache HTTP Server and supporting files. By default, the files are installed in

/usr/local/mapguideopensource/webserverextensions/apache2

If you used the --prefix Prefix option with the build_apt.sh command, the files are installed in

Prefix /webserverextensions/apache2

The installation script also creates mapguide.conf in the apache2/conf directory. This contains the necessary configuration directives. mapguide.conf is included by httpd.conf.

The Web Extensions directory structure makes use of aliases to simplify client-side URLs. To test whether the installation was successful and the aliases are set up properly, start the MapGuide Server. From the server installation directory, execute

./mgserver.sh

Using a Web browser, test the following URLs:

http://localhost:8008

This URL should display the standard Apache welcome page.

http://localhost:8008/mapguide/mapagent/mapagent.fcgi?OPERATION=ENUMERATERESOURCES&VERSION=1.0.0&RESOURCEID=Library://

This URL should return an XML document listing the contents of the MapGuide repository. Enter Administrator for the user id and admin for the password.

http://localhost:8008/mapguide/mapagent/index.html

This URL is a set of test forms for the map agent. The .html and .js files should be removed from the mapagent directory in a production environment.


Configuring PHP

The installation procedure installs PHP and supporting files. By default, the files are installed in

/usr/local/mapguideopensource/webserverextensions/php

If you used the --prefix= Prefix option with the build_apt.sh command, the files are installed in

Prefix /webserverextensions/php

The file php.ini-mapguide in the LinuxApt directory is used as a template for creating php/lib/php.ini. Paths in the template are changed to reflect the installation directories.

To check if PHP has been installed successfully, test the following URLs:

http://localhost:8008/mapguide/phpinfo.php

This URL should display the standard PHP info page. The string MapGuideApi should appear midway through the page.

http://localhost:8008/mapguide/mapadmin/login.php

This URL should display the MapGuide site administration page. Enter Administrator for the user id and admin for the password.


Configuring Tomcat

If you choose to install Tomcat, the installation procedure installs it and supporting files. By default, the files are installed in

/usr/local/mapguideopensource/webserverextensions/tomcat

If you used the --prefix= Prefix option with the build_apt.sh command, the files are installed in

Prefix /webserverextensions/tomcat

Tomcat is attached to Apache using mod_jk. For additional reference material, see

http://tomcat.apache.org/connectors-doc/howto/quick.html

mod_jk is built from source as part of build_apt.sh and installed to the apache/modules directory.

The following files are created and/or modified by build_apt.sh:

  • Prefix /webserverextensions/apache2/conf/mapguide.conf

    Additional directives for configuring mod_jk are added in a Tomcat Integration section at the end of the file.

  • Prefix /webserverextensions/apache2/conf/workers.properties

    This new configuration file is added for Tomcat integration.

  • Prefix /webserverextensions/tomcat/server.xml

    Additional directives to enable UTF-8 encoding of URLs are added to the default server.xml file.

  • Prefix /webserverextensions/tomcat/conf/Catalina/localhost/mapguide.xml

    This new Tomcat context file for MapGuide points Tomcat at the www directory.

In addition to these files, the following environment variables are added before Tomcat is started:

  • export LD_LIBRARY_PATH= Prefix /webserverextensions/lib: Prefix /lib
  • export JAVA_OPTS="-Djava.library.path=$LD_LIBRARY_PATH"

To check if Tomcat has been installed successfully, test the following URLs:

http://localhost:8080

You should see the Tomcat welcome page.

http://localhost:8008/mapguide/mapviewerjava/fake.jsp

This tests that Apache/Tomcat integration is working. It should return a Tomcat 404 error.

http://localhost:8008/mapguide/mapviewerjava/bufferui.jsp

This tests that Java Web Extensions are working. It should display an HTML page titled “Create a Buffer”.

http://localhost:8008/mapguide/mapviewerajax/bufferui.jsp

This verifies that the redirect works properly. It should display the “Create a Buffer” page.


Verifying the Configuration

You can run some simple tests to ensure that the Map Agent and Web Server Extensions are configured properly.

Testing the MapAgent

Open a web browser and go to the following URL. If the Web Server Extensions are not running on your local machine, replace localhost with the name or IP address of your server.

http://localhost:8008/mapguide/mapagent/mapagent.fcgi?OPERATION=ENUMERATERESOURCES&VERSION=1.0.0&LOCALE=en&RESOURCEID=Library://&TYPE=&DEPTH=-1

Enter Administrator for the user id and admin for the password. Both are case-sensitive.

If the Map Agent is running properly, you will get an XML document describing the resources in the repository.

Testing the Site Administrator

Ensure that the MapGuide Server is running. Open a web browser and go to the following URL.

http://localhost:8008/mapguide/mapadmin/login.php

Enter Administrator for the user id and admin for the password. Both are case-sensitive.

If the Site Administrator is configured properly, you will get a Manage Servers page which lists all the servers configured in the MapGuide Site.

Testing the Web Server Extensions

You can check that the Web Extensions are correctly set up. If your application development language is PHP, go to this URL in a web browser:

http://localhost:8008/mapguide/mapviewerajax/ajaxviewer.php?WEBLAYOUT=Library://ATest.WebLayout

If your application development language is JSP, go to this URL in a web browser:

http://localhost:8008/mapguide/mapviewerajax/ajaxviewer.jsp?WEBLAYOUT=Library://ATest.WebLayout

Because the web layout ATest does not exist in the MapGuide repository, you should see the following error:

Resource was not found: Library://ATest.WebLayout

This error is returned by the AJAX Viewer script. This shows that the Web Server Extensions are correctly enabled to receive and process requests.