Tutorial background¶
Tutorial Timeframe¶
While some users can go through this tutorial in one day, those who work on each example in detail can probably expect to finish in one week.
Tutorial Data¶
The dataset used in this tutorial was taken from the U.S. Department of the Interior’s National Atlas of the United States (which is no longer available, but was hosted by data.gov). The dataset was clipped to the upper great lakes region (Minnesota, Michigan, and Wisconsin) to reduce storage size. Additional raster images were added courtesy of the TerraSIP project at the University of Minnesota. When using this tutorial, you are encouraged to use your own dataset.
Like MapServer itself, this tutorial is open and customizable to anyone. This was done in the hope that someone (or some folks) will help design and develop it further.
Download the data (and all html files) for this tutorial at https://download.osgeo.org/mapserver/docs/mapserver-tutorial.zip .
Before Using the Tutorial¶
There are some prerequisites to using this tutorial:
Users will need to have a web server installed and running on their computer. This web server has to have support for common gateway interface (CGI) programs.
Users should have a basic understanding of web servers and internet security. A poorly configured web server can easily be attacked by malicious people. At the very least your software installation will be corrupted and you’ll lose hours of productivity, at worst your computer can be used to attack other computers on the internet.
It is recommended that users of this tutorial read the Introduction to MapServer before proceeding with this tutorial.
To use this tutorial, users will need to have a MapServer CGI program (mapserv or mapserv.exe) installed in their systems. MapServer source code is available for download here. Documentation exists on how to compile and install MapServer:
for UNIX users, please read the MapServer UNIX Compilation and Installation HOWTO.
Windows users should read the MapServer Win32 Compilation and Installation HOWTO
In addition, precompiled binaries exist for a number of platform (see the download page).
Windows, UNIX/Linux Issues¶
Paths¶
This tutorial is packaged for Windows users, but should work with minimal changes on UNIX or other platforms. The main differences are the paths in the map files. Windows users need to specify the drive letter of the hard disk where their tutorial files reside. Here’s an example:
A UNIX map file might include a parameter like this:
SHAPEPATH "/data/projects/tutorial/data"
In Windows, the same parameters might look like this:
SHAPEPATH "C:/data/projects/tutorial/data"
or:
SHAPEPATH "C:\data\projects\tutorial\data".
Notice that either slash or backslash works in Windows. The usual backslash may work well for you if you want to make a distinction between virtual (as in URLs or web addresses) and local paths in your map file. However, if you plan to move your application to UNIX at some point, you’ll have the tedious task of switching all backslashes to slashes.
While we’re on the subject of paths, keep in mind that paths in mapfiles are typically relative to the system’s root directory: the slash (“/”) in UNIX or some drive letter (“C:”) in Windows. This is true except when specifically asked to enter a URL or when referencing a URL. When working with HTML template files, paths are relative to the web server’s root directory. i.e., “/tutorial/” is relative to “https://demo.mapserver.org/”. Please read this for a few insights on URLs.
Executable¶
Another issue is that UNIX executable files don’t contain a .EXE extension, but they do in Windows. So you might have to adjust all instances of “/cgi-bin/mapserv.exe” to “/cgi-bin/mapserv”.
Other Resources¶
Other documentation exist to give you better understanding of the many customizations MapServer offer. Please visit the MapServer documentation page at https://mapserver.org/documentation.html . There you will find many HOWTO documents, from getting started to using MapScript, a scripting interface for MapServer.