MapServer for Windows (MS4W)

Author: Jeff McKenna, DM Solutions Group Inc.
Contact: http://lists.maptools.org/mailman/listinfo/ms4w-users (mailing list)
Revision: 1.12
Last Updated:2005-10-27

Table of Contents

Introduction

Welcome to MS4W, the quick and easy installer for setting up MapServer For Windows and its accompanying applications (e.g., Chameleon, MapLab, etc.). The purpose of this package is to allow novice to advanced MapServer users to quickly install a MapServer development environment on their Windows systems. The reasons for needing to do this are diverse but, in general, this package supports: developers who want to get to a stable state quickly, trainers who need an easily-installed configuration identical across multiple installs, and novices who need help just getting all the needed bits and pieces together.

Design

The MS4W package is designed to perform a full installation of Apache, PHP, MapServer (cgi), PHP/MapScript, and to provide the capability to install additional applications easily and quickly. The simplest way to do this on Windows is to provide a predetermined directory structure and force everything into that mold.

The directory structure, while fixed within itself, is designed to be somewhat portable. While it needs to be installed at the root of a hard drive, it doesn't have to be the C: drive. Moving the package to the root of a different drive is simple - just copy it there. To move it to a subdirectory is more difficult - you'll need to search for /ms4w in all the files and replace it with your new path.

The design also accommodates simple upgrades to the core package and to applications, without affecting the local configuration or the configuration of other installed applications.

Currently, the MS4W installation is considered neither secure nor stable. It should not be used for production purposes. Do not expect to get any support for using this package in such an environment.

Contents

The following are included in the base package:

MapServer Version Information

MapServer version 4.6.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP 
OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE 
SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER 
SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER INPUT=JPEG INPUT=POSTGIS 
INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG

MapServer version 4.4.2 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP 
OUTPUT=PDF OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER 
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT 
SUPPORTS=WCS_SERVER INPUT=EPPL7 INPUT=POSTGIS INPUT=OGR INPUT=GDAL 
INPUT=SHAPEFILE

Directory Structure

  • ms4w/ - the main directory, assumed to be at the root of a drive,

    normally C:

  • ms4w/Apache - the Apache installation

  • ms4w/Apache/bin - the Apache binaries

  • ms4w/Apache/cgi-bin - the location of mapserv.exe and its supporting

    libraries, and php.ini, php.exe

  • ms4w/Apache/conf - the Apache configuration files. These should not

    be modified. Place all application-specific and local httpd.conf files in /ms4w/httpd.d (see the README.txt in that directory)

  • ms4w/Apache/error - error files for Apache to use

  • ms4w/Apache/htdocs - the Apache Web root directory, you shouldn't

    install much in here except perhaps for testing.

  • ms4w/Apache/icons - icons used by Apache

  • ms4w/Apache/include - include directory for compiling against Apache

  • ms4w/Apache/lib - lib files for building against Apache

  • ms4w/Apache/logs - log files for Apache are stored here, this should

    be archived or cleaned every so often.

  • ms4w/Apache/manual - the Apache manual pages.

  • ms4w/Apache/modules - modules for Apache

  • ms4w/Apache/php - the PHP installation

  • ms4w/Apache/php/extensions - location of phpmapscript dll

  • ms4w/Apache/proxy - apache proxy configurations, not used by MS4W

  • ms4w/apps - put all applications in subdirectories here
    • currently contains pgsql75win and owtchart

  • ms4w/gdaldata - supporting files for GDAL data formats

  • ms4w/gdalplugins - place dlls here that are required for gdal plugins

    e.g. 'gdal_MrSID.dll'

  • ms4w/httpd.d - put all application-specific and local httpd.conf

    files here (see the README.txt in that directory)

  • ms4w/proj - an installation of PROJ.4
    • the epsg file used is /ms4w/proj/nad/epsg

  • ms4w/tmp - temporary files go here. This should be cleaned regularly

  • ms4w/tmp/ms_tmp - temporary files that need to be Web-accessible go

    here (i.e. image files created by mapserver). This is available as /ms_tmp/ via URL. Normally this means that your MAP files would have an IMAGEPATH of /ms4w/tmp/ms_tmp/ and a IMAGEURL of /ms_tmp/

  • ms4w/tools - contains useful tools such as the gdal/ogr utilities and

    mapserv utilities

How to Install MS4W

A. Upgrading from an older version of MS4W:

If you already have MS4W installed please do the following:

  • find the name of your Apache service by opening the Services window (on WinXP StartMenu/Settings/ControlPanel/Administrative Tools/Services)
  • open a DOS command window and 'cd' to yourpathto/ms4w/Apache/bin
  • run the following command:
Apache -k stop -n "insert apache service name here"
  • you should see the following message in the command window:
The "your service name" service is stopping.
The "your service name" service has stopped.
  • then run the following command:
Apache -k uninstall -n "insert apache service name here"
  • you should see the following message in the command window:
Removing the "your service name" service
The "your service name" service has been removed successfully.
  • your old apache service has now been removed
  • make sure no files or other services point the your ms4w folder. If your browser is currently open and you are a viewing an ms4w page you will not be able to rename the ms4w folder. Therefore you must close all ms4w documents, all ms4w browser windows...make sure no running files point to the ms4w folder.
  • rename the old ms4w folder to something like 'ms4w-old'
  • extract the ms4w_xx.zip file to the root of a drive on your machine
  • if successful, you should have a new directory named 'ms4w' at the root of the drive you chose (e.g. C:/ms4w or D:/ms4w ).
  • follow the rest of the install instructions in /ms4w/README_INSTALL.txt to start apache...

B. If you are extracting MS4W for the first time:

Please read through the following instructions before starting your installation.

  1. To install the MS4W .zip file, use a compression program (e.g., WinZip) to extract the package at the root of a drive, e.g., drive C:. If successful, you should have a new directory named 'ms4w' at the root of the drive you chose (e.g. C:/ms4w).

  2. Start your MS4W Apache Web Server by running /ms4w/apache-install.bat (at the command line or by double-clicking it). This file installs Apache as a Windows service (called "Apache Web Server") so that it starts whenever your machine is restarted. When executed, a DOS window should pop up with the following message:

    The Apache Web Server service is starting.

    The Apache Web Server service was started successfully.

    This means that Apache is running and installed as a service.

    NOTE for Win95,98,ME users:

    You will not be able to install Apache as a service, so instead you will have to manually start Apache each time, by clicking on /ms4w/Apache/bin/apache.exe. An empty DOS window will open, which means Apache is running. To stop Apache you will have to close this empty DOS window.

  3. To test that Apache is running properly, open your Web browser and find your local host Web service by entering one of the following URLs:

    http://localhost/

    or

    http://127.0.0.1/

    You should now see the main MS4W page in your Web browser. This gives you general information about your install along with configuration information. If this is your first time using MS4W it is very important that you review the listed "Features" installed within MS4W, and test them by selecting each link found on this page.

  4. Technically, at this point, MS4W is installed! However, as you may have noticed from the MS4W main index.html page, there are no applications running. What this means is that there are no Web applications like MapLab or Chameleon found within MS4W's Web-accessible directory, /ms4w/apps/. The MS4W-configured Web applications can be found on http://maptools.org/ as separate zip files.

  5. To install these Web application into /ms4w/apps/ all that is required is to unzip the Web application compressed file at the same root directory as MS4W (e.g., C:).

    Two things should happen when uncompressing this file. First, the Web application directory should appear within /ms4w/apps/. Second, a new httpd_*.conf file should be added to /ms4w/httpd.d/httpd_*.conf. (The /httpd.d/ directory contains Apache configuration files that define which files on your computer/server are Web-accessible. For each Web application that you install, a new configuration file will be found.)

  6. The definitions of these Web-accessible directories are called Web Aliases. In order to activate a Web Alias you must restart Apache. To test your latest installed application, go to the MS4W main index.html page (i.e., http://localhost/). In the applications section you should now find a link to the application you just installed. Select the link to the recently installed application to see if it is configured correctly. Another option is find the Web Alias for your application and call it from your Web browser directly. For example, if you have installed the latest MS4W version of MapLab, the chances are the Web Alias is "maplab". To go to the MapLab index page, simply enter http://localhost/maplab/.

    Note: Applications with configuration files (e.g., MapLab and Chameleon) generally do not require any editing of their files in order to work. Just unzip to the appropriate driver root and restart Apache.

    WARNING: It is very possible that you may wish (but not encouraged!) to run multiple versions of the same product. For example, Maplab 2.0 (mapserver_36) vs. MapLab 2.1 (mapserver_4.0). When installing these ms4w MapLab application packages, you will notice when unzipping MapLab that the httpd_maplab.conf file found under ./ms4w/httpd.d/ will be overwritten by the MapLab you are currently installing. The reason for this is that the MapLab Alias stays the same from version to new version of MapLab. So, if you overwrite the httpd_maplab.conf when unzipping and then restart Apache, you will get the latest version of Maplab that you just installed. To run both MapLab simply follow the instructions in Step 7.

  7. You also can create new Web Alias(es). To configure your own personal Web Alias(es), follow the instructions in /ms4w/httpd.d/README_HTTPD.txt

C. Troubleshooting

Warning: dl(): Unable to load dynamic library '/ms4w/Apache/php/extensions/php_mapscript_42.dll'

  1. Make sure that the dll in question exists in the specified location (/ms4w/Apache/php/extensions/). If this dll is not in that location, you might have to modify the application to point to a different version of the dll (e.g. you might have php_mapscript_46.dll in the extensions directory, and maplab might be configured for php_mapscript_42.dll which is not in the extensions directory).
  2. This php_mapscript dll requires several other dlls, and the problem may be that one is missing on your system. In order to hopefully get more information on what dll is missing, go to a command prompt, and do the following:
cd ms4w\Apache\cgi-bin

php C:/ms4w/Apache/htdocs/phpinfo_mapscript_**.php  (replace ** with the mapscript version)

A windows error window should open with a message like:

   The dynamic link library ***** could not be found in the specified path...
   
Locate this missing dll and copy it either to /ms4w/Apache/cgi-bin/ or your
system32 folder.
  1. If you are still unsure what dll is causing this unable to load dynamic library error, a useful utility to find what associated dlls are missing on your system is Dependency Walker. Download the utility, execute the exe, and open your php_mapscript dll.

The dynamic link library MSVCP60.dll could not be found in the specified path...

This is a microsoft runtime library that is apparently not on all Windows systems by default. Download the dll (possibly from here) and copy it to your System32 directory.

Clicking on apache-install.bat flashes a DOS window and does not install the service

To see the exact error message, open a Command window, and execute the 'apache-install.bat' file from a DOS prompt.

cd ms4w

apache-install.bat

Only one usage of each socket address (protocol/network address/port) is normally permitted. : make_sock: could not bind to address 0.0.0.0:80 no listening sockets available, shutting down

Apache with MS4W is configured to use port 80. Your system might be already using this port (IIS could cause this for example). If you want to change the port that Apache uses modify the following file:

/ms4w/Apache/conf/httpd.conf

line 120: Listen 80

Other Problems...

  1. Search the mailing list archives to see if someone has encountered/solved your same issue.
  1. If your issue has not been brought up on the mailing list and dealt with, submit a question to the MS4W mailing list. Include the steps to reproduce your problem, and state your exact error message. Also specify which version of MS4W you are using.

Applications

The following applications come with a pre-configured install package for MS4W. Go to http://www.maptools.org/ms4w/index.phtml?page=downloads.html to find the desired package, and extract the packages to the root of the drive that MS4W is installed on (e.g. C:).

Chameleon

  • chameleon_ms4w-xxxx.zip

    • /ms4w/apps/chameleon - an installation of Chameleon.
      • admin page URL is: /chameleon/admin/
      • docs URL is: /chameleon/docs/
      • help viewer URL is: /chameleon/help/
      • samples URL is: /chameleon/samples/
      • CWC2 Service Instance URL is: /chameleon/cwc2/

GMap Sample Application

  • gmap_ms4w.zip

    • /ms4w/apps/gmap - an installation of the Gmap phpmapscript demo application
      • URL is /gmap/gmap75.phtml.

ka-Map

  • kamap_xxx_ms4w.zip

    • ms4w/apps/kamap-xxx - an installation of ka-Map Javascript API.
      • URL is /kamap/.

MapLab

  • maplab_ms4w-xxx.zip

    • ms4w/apps/maplab-xx - an installation of MapLab.
      • URL is /maplab/.

OGC Workshop

  • ms_ogc_workshop.zip

    • ms4w/apps/ms_ogc_workshop - an installation of the MapServer OGC workshop.
      • URL is /ms_ogc_workshop/.

Postgres

  • pgsql75win_ms4w.zip

    • unsupported PostgreSQL 7.5 / PostGIS for Windows
    • installed in /ms4w/apps/pgsql75win

About this Document

Revision History

Revision Date Author Comment
1.00 2003/09/10 DMR converted from text format
1.01 2003/10/18 CT, DMR added additional material
1.02 2004/07/21 JM updated for 0.9 release
1.03 2004/11/09 JM updated for 1.0 release
1.04 2004/11/29 JM updated for 1.0.1 upgrade
1.05 2004/12/16 JM updated for 1.0.2 upgrade
1.06 2004/12/22 JM updated for 1.0.3 upgrade
1.07 2005/05/25 JM updated for 1.1 release
1.08 2005/06/22 JM updated for 1.2 release
1.09 2005/09/15 JM added not for win98 users, and MS version info
1.10 2005/10/26 JM converted to rSt/html, added troubleshooting

Copyright/Licensing Information

Copyright (c) 2005, Jeff McKenna, 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 PARTICULAR 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.

Feedback

Send any comments or suggestions to the MS4W mailing list, which you can join at: http://lists.maptools.org/mailman/listinfo/ms4w-users