Installing the MapServer CGI Program and the Tutorial
Before you can actually go through the tutorial, you'll need to make sure you have your web server running and the MapServer CGI program (mapserv or mapserv.exe) installed in your "cgi-bin" directory. For those working in Microsoft Windows environment, it is recommended that you use the MapServer for Windows (MS4W) package developed by Gateway Geomatics. This is a complete web mapping environment for Windows and includes the Apache web server, GDAL, PROJ, MapServer, and all required libraries and useful utilities.
To install the tutorial under MS4W, simply unzip the tutorial.zip archive to C:\ (or whichever drive MS4W is installed) and restart the web server. The tutorial files will be installed under \ms4w\apps\tutorial and an Apache configuration snippet will be installed as \ms4w\httpd.d\httpd_tutorial.conf.
For those who are already familiar with web programming, you can also try to compile MapServer yourself. Windows developers can compile MapServer by following the Compiling on Win32 howto. If you don't have a compiler or don't want to waste precious time compiling MapServer (and libraries), just download from one of the sites mentioned above.
For Unix and Unix-like operating systems, you can search google for binary distribution for your particular platform. If nothing turns up, you can always ask the MapServer-Users mailing list if such binaries exist. If all else fail, you'll have to compile MapServer and the associated libraries. The compilation and installation how-to for Unix is available at https://mapserver.org/installation/unix.html.
Assuming you've got the MapServer CGI program, follow the steps below
to install: (note that MS4W users already have the following configured, and can proceed to the tutorial)
If compiled in Unix, just copy the binary "mapserv" to your "cgi-bin" directory. On a locally compiled Apache server this will be on "/usr/local/apache/cgi-bin/" or /usr/local/apache2/cgi-bin". If your web server comes as part of your OS distribution, look for the "cgi-bin" directory or consult your OS's documentation.
If you compiled on Win32 platform, copy the binary "mapserv.exe"
to your "cgi-bin" or "scripts" directory. If
you compiled the projection support for MapServer, copy the contents
of "proj-4.4.7\nad" subdirectory to "C:\Proj\nad".
You'll also need to copy all your supporting libraries to a directory
that's part of your system PATH. This would typically be "C:\Windows\System"
or "C:\Winnt\System32" but you can always add a different
directory in your system (not user) path. If your web server is
Apache, the "cgi-bin" directory is typically in "C:\Program
Files\Apache Group\Apache\cgi-bin". If you are using Microsoft
IIS, the "cgi-bin" directory is typically called "scripts"
and is located in "C:\Inetpub\scripts". As with Unix,
consult your web server's documentation for more information about
"cgi-bin" and CGI programs.
If you are using Win32 binaries downloaded from the MapServer
web site, unzip the package to "C:\MapServer". From "C:\MapServer"
copy "mapserv.exe" to your "cgi-bin" directory.
In Apache this would typically be "C:\Program Files\Apache
Group\Apache\cgi-bin" and in Microsoft IIS it is "C:\Inetpub\scripts".
Copy the files from "C:\MapServer\lib" to C:\Windows\System
or C:\Winnt\System32, whichever is appropriate for your Windows
version. (Alternatively, you can edit your system PATH to include
"C:\MapServer\lib". In this way you don't have to copy
the library files to your system directory.) Move "C:\MapServer\Proj"
to "C:\Proj". This is required for projection support.
As with Unix, consult your web server's documentation for more information
about "cgi-bin" and CGI programs.
Test to make sure that your MapServer CGI program is working.
With your web server running, open this URL on a web browser: http://localhost/cgi-bin/mapserv?
(on *nix) or http://localhost/cgi-bin/mapserver.exe? or http://localhost/scripts/mapserver.exe?
(on Windows). You should get the following message:
No query information to decode. QUERY_STRING is set, but empty.
This means that MapServer is working but you haven't supplied it
with anything to process. If you've gotten this far and you've got
a different message than above, the first thing to do is to check
your error log and see what cause the message to appear. This typically
means that you are missing your library files (dll's). Rectify the
problem if you can, or check the MapServer
FAQ. Failing that, check the MapServer
Users mailing list archives, and if the archive isn't helpful,
send an e-mail to the MapServer
Users mailing list (you must be subscribed to send e-mail to
If you downloaded a copy of the tutorial, change the name of
"mapserv" or "mapserv.exe" to "mapserv50"
or "mapserv50.exe". The other option is to change each
occurence of "mapserv50 "or "mapserv50.exe"
back to "mapserv" or "mapserv.exe" in the example
files--a very tedious process. This tells you that you can rename
the MapServer CGI binary to whatever you want. It isn't recommended
but if you run several versions of MapServer on the same machine,
you really don't have a choice.
If you downloaded the MapServer tutorial, the easiest way to
install it is to unzip the archive to your web server's document
root directory--that's the "htdocs" directory in Apache
or "C:\Inetpub\wwwroot" in IIS. You will then have to
edit your html files to change every occurence of "map=/data/projects/tutorial/example*.map"
(Example: for example1-1.html, you'd change the occurence of "map=/data/projects/tutorial/example1-1.map"
to "map=C:/Inetpub/wwwroot/tutorial/example1-1.map") The
"*" means change whatever character/s follow after "example".
You can make this changes as you go through the examples.
You need to make a "tmp" directory and the easiest
way is to create "tmp" directory within Apache's "htdocs"
directory or IIS's "wwwroot" directory. You want to make
sure that your web server user account (that's usually "nobody"
in Unix and "IUSR_MACHINENAME" in IIS--MACHINENAME is
the name of your computer). For security, You also want to make
sure that users don't have execute permission in this directory.
(In Unix and while working as "root", run the commands
"chmod a+w /your/htdocs/directory/tmp" and "chmod
a-x /your/htdocs/directory/tmp". In Windows, you can use IIS
management console to change the permissions.) You will then need
to change the value of every occurence of the IMAGEPATH mapfile
keyword from "/data/tmp/" to "/your/htdocs/directory/tmp/"
(or in Windows, "C:/your/htdocs/directory/tmp" or "C:/Inetpub/wwwroot/tmp").
If you followed the directions up to this point you can now begin your
journey into the MapServer realm... Good luck!
Go to the tutorial
| Download the tutorial
Created by Pericles S. Nacionales
Maintained by Jeff McKenna, Gateway Geomatics
Last updated: 2020-03-13