Abstract
This document describes how to install Chameleon 2.0 on your system.
Last Updated: 2004/12/22
Table of Contents
This document is intended to help you get Chameleon 2.0 installed on your Windows or Linux server. It provides step-by-step instructions on how to proceed, based on a handful of common installation scenarios. If, after thoroughly reading this document and trying out its instructions, you have further installation questions, please refer to the For More Information section.
Once Chameleon is installed, you will likely have to change some of the administration and configuration parameters. A "Chameleon Administrator's Guide" will be developed in the near future...for now if you are working on Windows the MS4W Chameleon installer package is recommended. Otherwise the config file is located at \\chameleon\config\chameleon.xml.
If you have previously used Chameleon 1.0 (also known as CWC2), take note. The CWC2 Service Instance, which was an integral part of the main CWC2 product, has been separated out from the base functionality of Chameleon 1.99/2.0. While the Service Instance is still available and is downloaded/installed with standard Chameleon, you need to "turn it on" and configure it before it can be used. For more information, refer to the "CWC2 Service Instance" document.
If you are using the Windows operating system, the best and quickest way to get up and running with Chameleon is to use the MS4W (MapServer for Windows) installer utility. After installing the base MapServer package, you can then add the latest Chameleon 2.0 add-on package. Within a few minutes, you should be up and running!
However, please note that MS4W comes with a pre-configured Web Server (Apache) and supporting files. If you are already using a Web Server, follow the customized installation instructions to integrate Chameleon into your existing Websites.
Information and downloads for the MS4W package (and its add-ons) can be found on MapTools.org at http://www.maptools.org/ms4w/.
If you are using the Linux operating system or need to do a custom Windows installation, please refer to the section Customized Installations.
Before installing Chameleon 2.0 on your Windows system, please make sure that you have the following technologies properly installed.
Table1. Required Technologies
| Technology | Details | Where to Go... |
| PHP 4.3.x | web scripting language | http://www.php.net/downloads.php |
| Web Server | e.g., Apache, IIS, PWS, etc. | http://www.apache.org, http://www.microsoft.com, etc. |
| PHP MapScript | module enabling MapServer's MapScript functions | http://www.maptools.org/php_mapscript/ |
| PROJ.4 | Must be in system PATH - e.g., c:\ or c:\windows\system32. Alternatively, you can configure through metadata (see MapServer documentation). | http://proj.maptools.org/ |
From this point on, this guide assumes that you have all required technologies installed and properly configured.
Most Windows users will use the MS4W installer, but if you want to do a custom Windows installation, please perform the following steps:
Unzip Chameleon 2.0 to the directory of your choice. This creates the following base directories:
chameleon<version>\admin
chameleon<version>\config
chameleon<version>\cwc2
chameleon<version>\data
chameleon<version>\docs
chameleon<version>\etc
chameleon<version>\htdocs
chameleon<version>\samples
Create the following directories in a Web-accessible and Webuser-writable directory:
ms_tmp
ms_tmp/buttons
For example:
c:\tmp\ms_tmp\
c:\tmp\ms_tmp\buttons\
(In this example, c:\tmp\ms_tmp would be Web-accessible and Webuser-writable.)
Create the following aliases (Apache) or virtual directories (IIS):
/chameleon/
/chameleon/admin/
/chameleon/docs/
/chameleon/samples/
/chameleon/cwc2/contexts/ (for the CWC2 Service Instance)
/chameleon/cwc2/templates/ (for the CWC2 Service Instance)
/chameleon/cwc2/ (for the CWC2 Service Instance)
/ms_tmp/
There are many different ways of going about creating these aliases. For example, in Apache:
Alias /chameleon/admin "/ms4w/apps/chameleon/admin/htdocs"
<Directory "/ms4w/apps/chameleon/admin/htdocs/">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
Alias /chameleon/docs "/ms4w/apps/chameleon/docs/html"
<Directory "/ms4w/apps/chameleon/docs/html">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
Alias /chameleon/samples "/ms4w/apps/chameleon/samples/htdocs"
<Directory "/ms4w/apps/chameleon/samples/htdocs">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
Alias /chameleon/cwc2/contexts "/ms4w/apps/chameleon/cwc2/contexts"
<Directory "/ms4w/apps/chameleon/cwc2/contexts">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
Alias /chameleon/cwc2/templates "/ms4w/apps/chameleon/cwc2/templates"
<Directory "/ms4w/apps/chameleon/cwc2/templates">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
Alias /chameleon/cwc2 "/ms4w/apps/chameleon/cwc2/htdocs"
<Directory "/ms4w/apps/chameleon/cwc2/htdocs">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
Alias /chameleon "/ms4w/apps/chameleon/htdocs"
<Directory "/ms4w/apps/chameleon/htdocs">
AllowOverride None
Options Indexes FollowSymLinks Multiviews
Order allow,deny
Allow from all
</Directory>
For example, in IIS (assuming that you are using Default Web Site configuration with Home Directory specified as c:\inetpub\wwwroot):
Website Location: webroot
Name: chameleon
Virtual Directory Parent: None (site root)
Virtual Directory Name: chameleon
File Path: <drive>:\path\to\chameleon\htdocs
IIS Permission: Default Permissions
IUSR Permissions: read/execute
ie: siteroot\chameleon
Name: admin
Virtual Directory Location: chameleon
Virtual Directory Name: admin
File Path: <drive>:\path\to\chameleon\admin\htdocs
IIS Permission: Default Permissions
IUSR Permissions: read/execute
ie: siteroot\chameleon\admin
Name: docs
Virtual Directory Location: chameleon
Virtual Directory Name: docs
File Path: <drive>:\path\to\chameleon\docs\html
IIS Permission: Default Permissions
IUSR Permissions: read/execute
ie: siteroot\chameleon\docs
Name: samples
Virtual Directory Location: chameleon
Virtual Directory Name: samples
File Path: <drive>:\path\to\chameleon\admin\htdocs
IIS Permission: Default Permissions
IUSR Permissions: read/execute
ie: siteroot\chameleon\samples
Name: cwc2
Virtual Directory Parent: None (site root)
Virtual Directory Name: cwc2
File Path: <drive>:\path\to\chameleon\cwc2\htdocs
IIS Permission: Default Permissions
IUSR Permissions: read/execute
ie: siteroot\cwc2
Name: templates
Virtual Directory Location: cwc2
Virtual Directory Name: templates
File Path: <drive>:\path\to\chameleon\cwc2\templates
IIS Permission: Default Permissions
IUSR Permissions: read/execute
ie: siteroot\cwc2\templates
Name: contexts
Virtual Directory Location: cwc2
Virtual Directory Name: contexts
File Path: <drive>:\path\to\chameleon\cwc2\contexts
IIS Permission: Default Permissions + Write
IUSR Permissions: read/execute
ie: siteroot\cwc2\contexts
Name: ms_tmp
Virtual Directory Parent: None (site root)
Virtual Directory Name: ms_tmp
File Path: <drive>:\path\to\temp_writable_folder\ms_tmp
IIS Permission: Default Permissions
IUSR Permissions: read/write
ie: siteroot\ms_tmp
Copy \config\chameleon.xml-dist to \config\chameleon.xml.
Edit the following properties:
web_server_path
This is the URL to chameleon.php. You can use an alias (e.g., /chameleon/) or an absolute URL (i.e., starting with http://). Note: if you use a URL and set it to http://localhost/<path-to-chameleon>, then the app won't work from remote machines. As per Step 3, this value would be the Chameleon Alias/Virtual Directory.
mapscript_module
Mapscript module name (i.e., php_mapscript_<version>.dll ). For the latest version, visit http://www.maptools.org/ or http://mapserver.gis.umn.edu.
button_cache_path
Directory in which to write image files generated for buttons. This directory must be writable by the Web Server user and Web-accessible. For performance reasons, this directory should not be cleaned out automatically. As per Step 2, this would be c:\tmp\ms_tmp\buttons\.
button_cache_web_path
The URL where a browser can find cached button images. As per Step 2, this would be ms_tmp/buttons/.
tmp_web_path
The URL where a browser can find temporary files (e.g., images). As per Step 2, this would be ms_tmp/.
tmp_img_path
Directory where temporary image files are put. As per Step 2, this would be c:\tmp\ms_tmp\.
Test your installation now. Point your browser to http://127.0.0.1/<samples>/ and you should get an index page with links to several different Chameleon applications.
Apache
Note: the MS4W installer, which contains an Apache install, is available.
IIS
It can be challenging to configure IIS to recognize the default MS4W PHP installation. It is much quicker to grab the PHP installer (4.3.x) from www.php.net, install it at the root of a drive (e.g., D:\php), and allow the installer to perform configuration of IIS. For added security of multi-site IIS servers, remove the script mapping to *.php from the root server and apply it only to those sites and/or virtual directories where you need it.
You will most likely have to generate your own mapping for *.phtml. To do this correctly go to the Properties page for the site or virtual directory you wish to add the mapping to, then find the Home Directory tab. Three-quarters of the way down the resulting dialog is a Configuration Button - click it. Go to the App Mappings tab and add *.phtml (you will be required to find php.exe on the system) and select All Verbs. Do not test to see if the script exists (if it doesn't, then you're in trouble anyway).
If your application uses PROJ.4 (and it probably does), you may run into issues with it. If the PROJ.4 directory cannot be found in your application, you have to place the proj directory in a PATH directory. (There is an ENV VAR that you can place in your MapFile to point to a PROJ directory other than a PATH - consult the MapServer documentation.)
Note: you can get IIS lockdown from http://www.microsoft.com and run the program using the dynamic site template. This tool essentially removes unwanted script mappings (e.g., .printer) to reduce vulnerability.
Note: Microsoft also has a product called MSBA (Microsoft Baseline Security Analyzer). This tool allows users to seek vulnerabilities in the configuration of different components of the OS, including Web Servers. It may seem odd to use an MS product to detect MS problems, but it could help shed light on things (at the very least).
Before installing Chameleon 2.0 on your Linux system, please make sure that you have the following technologies properly installed.
Table2. Required Technologies
| Technology | Details | Where to Go... |
| PHP 4.2.3 | or greater (see note below) | http://www.php.net/downloads.php |
| MapServer/MapScript 4.0 | or greater | http://www.maptools.org/php_mapscript/ |
| GDAL 1.1.9 | or greater | http://gdal.maptools.org/index.html |
| Apache | or another Web Server | http://httpd.apache.org/download.cgi |
Note: PHP needs to have both GD (version 2.0 or higher) and FreeType support (Linkage = with freetype - not with TTF). Typically, this means running 'configure' with --with-gd=<dir> --with-freetype-dir=<dir>. The resulting output from running phpinfo would include a GD section like:
GD Support enabled
GD Version 2.0 or higher
FreeType Support enabled
FreeType Linkage with freetype
GIF Read Support enabled
GIF Create Support enabled
JPG Support enabled
PNG Support enabled
WBMP Support enabled
From this point on, this guide assumes that you have all required technologies installed and properly configured.
If you downloaded a set of precompiled binaries (Windows or Solaris), then follow the instructions for the binary package that you downloaded and proceed directly to the next section, Chameleon Core Installation.
Note: these instructions assume that you already have PHP set up with your Web Server.
See the following page for detailed MapScript build/install instructions: http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?PHPMapScript.
Configure MapServer with:
--with-wmsclient,
--with-proj,
--with-php=[your_php_directory], and
--with-gdal,
as a minimum.
make MapServer and place the mapscript/php3/php_mapscript.so file in your PHP extensions directory.
Create a temporary directory for MapServer to create and publish images. For example, create /tmp/ms_tmp/.
Configure your Web Server to be able to access this directory. For example, create a symlink from /var/www/html/ms_tmp/ to /tmp/ms_tmp/.
It is recommended that a cron job be created to delete the contents of this directory on a regular basis (hourly or daily, depending on usage).
Extract the chameleon_[VERSION].tar.gz file on the server. These instructions are written as if this was in /opt/. This creates a chameleon_[VERSION] directory. Rename it to be chameleon/. You should have the following subdirectories:
chameleon/
chameleon/config
chameleon/data
chameleon/htdocs
chameleon/htdocs/common
chameleon/htdocs/images
chameleon/htdocs/widgets
Configure your Web Server to be able to access /opt/chameleon/htdocs/. For example, create a symlink from /var/www/html/chameleon/ to /opt/chameleon/htdocs/.
Make sure directory chameleon/data is writable by the Web user. This is where cached capabilities and other temporary information are stored for the duration of a user's session.
Copy the file config/cwc2.xml-dist under the name cwc2.xml and edit it to suit your local settings (the Web-based interface is not ready). These settings are most likely to need changing:
Table3. Local Settings
| Setting | Change to |
| app_path | /opt/chameleon/htdocs/ |
| server_data_path | /opt/chameleon/data |
| wms_parse_file | /opt/chameleon/htdocs/common/wmsparse/wmsparse |
| default_template | path or URL to a user interface template file |
| default_context | path or URL to a context file that should be loaded by default |
| mapscript_module | php_mapscript.so |
| tmp_*_path | /tmp/ms_tmp/ |
| tmp_web_*_path | /ms_tmp/ |
WMSPARSE is an optional WMS capabilities parser. Chameleon can use a PHP-based parser if WMSPARSE is not available, but doing so is much slower and can timeout on large capabilities documents. To install WMSPARSE, follow the instructions for your platform/configuration below. You also need to make sure that the WMSPARSE setting in your chameleon.xml file is set to point at the correct executable file, otherwise the slower parser will be used. (This will be discussed in the upcoming "Chameleon Administrator's Guide" document, which has yet to be developed.)
Windows WMSPARSE Install
If installing on Windows, then Chameleon already comes with WMSPARSE.EXE pre-installed in the Chameleon directories.
WMSPARSE Install from Source
If you are installing from source, then you have to compile WMSPARSE and, for this, you need libxml2 installed. Then you can do the following:
cd /opt/chameleon/htdocs/common/wmsparse/
make
Precompiled WMSPARSE Install
If you installed a precompiled MapServer binary package, then it may have come with a 'wmsparse' already compiled. Simply copy it to the CWC2 directory and make sure it is executable:
cp /opt/mapserver/bin/wmsparse /opt/chameleon/htdocs/common/wmsparse/
chmod +x /opt/chameleon/htdocs/common/wmsparse/wmsparse
(The above lines assume that you installed the MapServer binary package under /opt/mapserver.)
If you were unable to answer all the questions you had about the s ubject of this document, other possible methods of obtaining information include:
There are several other Chameleon 2.0 documents that can be found on the Chameleon Documentation page (including some that are referenced in this document). Please look through these documents for answers to your questions.
You can pose a question on the Chameleon Mailing List and other members of the Community might be able to help you. In fact, searching the mailing list archive can often lead to the necessary information without having to pose a new question. To sign up to be a part of the mailing list, please visit here.
If you find what you believe to be a bug in Chameleon 2.0, please submit it to the public Bugzilla repository. This is by far the quickest way to get a bug in the product addressed. The mailing list should not be used for reporting bugs.
The numbering is in parallel with the revision control system. Missing numbers indicate minor maintenance revision updates.
| Revision History | ||
|---|---|---|
| Revision Number: 1.6 | Date: 2004/12/22 | Author: Jason Fournier |
| minor changes | ||
| Revision Number: 1.5 | Date: 2004/12/20 | Author: Jeff McKenna |
| minor changes and formatting | ||
| Revision Number: 1.4 | Date: 2004/11/13 | Author: Darren Redfern |
| further changes based on (JF's) review comments | ||
| Revision Number: 1.3 | Date: 2004/11/13 | Author: Darren Redfern |
| further changes based on review comments | ||
| Revision Number: 1.2 | Date: 2004/11/12 | Author: Darren Redfern |
| changes based on review comments | ||
| Revision Number: 1.1 | Date: 2004/11/11 | Author: Darren Redfern |
| first draft complete | ||
| Revision Number: 1.01 | Date: 2004/08/22 | Author: Darren Redfern |
| initial compilation in DocBook | ||
| Revision Number: 1.00 | Date: 2004/08/20 | Author: Paul Spencer |
| original text-only version | ||
Copyright (c) 2004, Paul Spencer, DM Solutions Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A ARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Input is appreciated. Send any comments or suggestions to the Chameleon Users mailing list at http://lists.maptools.org/mailman/listinfo/chameleon.