Building and Configure MapGuide Open Source 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:
- Download the J2SE Development Kit from http://java.sun.com/javase/downloads/index.jsp and install.
- Add JAVA_HOME=/usr/java/jdk1.6.0_01 to your environment. If you use a different version of the JDK, make the appropriate substitution.
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:
- aclocal
- libtoolize --force
- automake --add-missing --copy
- autoconf
- ./configure (with optional build flags)
- make
- make check
- 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:
- If you have already built MapGuide,
make clean
- ./configure --enable-optimized
- make
- 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:
- ./configure --enable-server=no
- make
- 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:
- ./configure --prefix=$HOME
- make
- 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:
This URL should display the standard Apache welcome page.
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:
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.
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.