Plaintext
MapGuide Open Source
Building and Configuring
on Linux
July 2006
Copyright© 2006 Autodesk, Inc.
This work is licensed under the Creative Commons Attribution-ShareAlike 2.5 License. You are free to: (i) copy, distribute, display and perform
the work; (ii) make derivative works; and (iii) make commercial use of the work, each under the conditions set forth in the license set forth at:
http://creativecommons.org/licenses/by-sa/2.5/legalcode. Notwithstanding the foregoing, you shall acquire no rights in, and the foregoing
license shall not apply to, any of Autodesk's or a third party's trademarks used in this document.
AUTODESK, INC., MAKES NO WARRANTY, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS, AND MAKES SUCH MATERIALS AVAILABLE
SOLELY ON AN "AS-IS" BASIS. IN NO EVENT SHALL AUTODESK, INC., BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR ARISING OUT OF ACQUISITION OR USE OF THESE MATERIALS. THE SOLE AND
EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE, IF ANY, OF
THE MATERIALS DESCRIBED HEREIN.
Trademarks
Autodesk, Autodesk Map, Autodesk MapGuide are registered trademarks of Autodesk, Inc., in the USA and/or other countries. DWF is a trademark
of Autodesk, Inc., in the USA and/or other countries. All other brand names, product names or trademarks belong to their respective holders.
Third Party Software Program Credits
Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Cold Spring Harbor Laboratory. Funded under
Grant P41-RR02188 by the National Institutes of Health.
Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 by Boutell.Com, Inc.
Portions relating to GD2 format copyright 1999, 2000, 2001, 2002, 2003, 2004 Philip Warner.
Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003, 2004 Greg Roelofs.
Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).
Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 John Ellson (ellson@graphviz.org).
Portions relating to JPEG and to color quantization copyright 2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) 1994, 1995, 1996,
1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Thomas G. Lane.
This software is based in part on the work of the Independent JPEG Group.
Portions relating to GIF compression copyright 1989 by Jef Poskanzer and David Rowley, with modifications for thread safety by Thomas Boutell.
Portions relating to GIF decompression copyright 1990, 1991, 1993 by David Koblas, with modifications for thread safety by Thomas Boutell.
Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 200 4Maurice Szmurlo and Johan Van den Brande.
Portions relating to GIF animations copyright 2004 Jaakko Hyvätti (jaakko.hyvatti@iki.fi)
This product includes PHP, freely available from http://www.php.net/
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
The Director General of the Geographic Survey Institute has issued the approval for the coordinates exchange numbered TKY2JGD for Japan.
Geodetic Datum 2000, also known as technical information No H1-N0.2 of the Geographic Survey Institute, to be installed and used within
this software product (Approval No.: 646 issued by GSI, April 8, 2002).
The OSTN97 coordinate transformation is © Crown Copyright 1997. All rights reserved.
The OSTN02 coordinate transformation is © Crown copyright 2002. All rights reserved.
The OSGM02 coordinate transformation is © Crown copyright 2002, © Ordnance Survey Ireland, 2002.
Portions of this software are copyright © 2005 The FreeType Project (www.freetype.org). All rights reserved.
1 2 3 4 5 6 7 8 9 10
Contents
Chapter 1 Building MapGuide on Linux . . . . . . . . . . . . . . . . . . . . 1
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Building and Installing Required Components . . . . . . . . . . . . . .2
Building and Installing Apache, PHP, and Tomcat . . . . . . . . . .2
Building and Installing FDO 3.0 . . . . . . . . . . . . . . . . . . .4
Other Requirements . . . . . . . . . . . . . . . . . . . . . . . . .4
Building the MapGuide Server and Web Server Extensions . . . . . . . .4
Obtaining the MapGuide Source Code . . . . . . . . . . . . . . . .4
Building OEM Components in the MapGuide Distribution . . . . .5
Building and Installing the Default Configuration . . . . . . . . .5
Building a Release Configuration . . . . . . . . . . . . . . . . . .6
Building Components Separately . . . . . . . . . . . . . . . . . .6
Installing in a Different Location . . . . . . . . . . . . . . . . . .6
Specifying FDO Locations . . . . . . . . . . . . . . . . . . . . . .7
Running the Server . . . . . . . . . . . . . . . . . . . . . . . . .7
Chapter 2 Configuring MapGuide Web Server Extensions on Linux . . . . . 9
Virtual Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . 10
Configuring Apache HTTP Server . . . . . . . . . . . . . . . . . . . . . 10
Configuring PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Configuring Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . 13
iii
Testing the Map Agent . . . . . . . . . . . . . . . . . . . . . . . 13
Testing the Site Administrator . . . . . . . . . . . . . . . . . . . 14
Testing the Web Server Extensions . . . . . . . . . . . . . . . . . 14
iv | Contents
Building MapGuide on
Linux 1
In this chapter
■ System Requirements
■ Building and Installing Required
Components
■ Building the MapGuide Server and
Web Server Extensions
1
System Requirements
MapGuide Open Source requires the following components:
■ Apache HTTP Server 2.xx
■ PHP 5.0.5
■ FDO 3.1.0
■ 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 3 with GCC 3.2.3, and
Fedora Core 4 with GCC 4.0.2.
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.05, and optionally Tomcat.
These are bundled into a single tarball available from www.osgeo.org. Building
and installing this bundle will ensure that the components are configured
properly for MapGuide.
MapGuide requires the J2SE Development Kit (JDK) 5.0. To install the JDK:
■ Download the J2SE Development Kit 5 (JDK 5.0) from
java.sun.com/j2se/1.5.0/download.jsp and install.
■ Add JAVA_HOME=/usr/java/jdk1.5.0_06 to your environment. If you use
a different version of the JDK, make the appropriate substitution.
2 | Chapter 1 Building MapGuide on Linux
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.0.5,
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 Apache, PHP, and Tomcat | 3
Building and Installing FDO 3.0
The source code for FDO Open Source is available from www.osgeo.org as a
gzipped tar file (fdo-3.0.0.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.0.0/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 www.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: 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 www.osgeo.org as a gzipped
tar file (mapguide-1.0.1.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.
4 | Chapter 1 Building MapGuide on Linux
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 OEM Components in the MapGuide Distribution | 5
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.
6 | Chapter 1 Building MapGuide on Linux
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.0, 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
Specifying FDO Locations | 7
Configuring MapGuide
Web Server Extensions on
Linux
2
In this chapter
■ Virtual Directory Structure
■ Configuring Apache HTTP Server
■ Configuring PHP
■ Configuring Tomcat
■ Verifying the Configuration
9
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
10 | Chapter 2 Configuring MapGuide Web Server Extensions on Linux
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/index.html
This is a simple HTML page. If it displays correctly then the aliases set up in
mapguide.conf are working correctly.
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.
Configuring PHP | 11
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
12 | Chapter 2 Configuring MapGuide Web Server Extensions on Linux
■ 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 Map Agent
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.
Verifying the Configuration | 13
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.
14 | Chapter 2 Configuring MapGuide Web Server Extensions on Linux