Welcome to the
MapServer Tutorial

Introduction
This tutorial was designed to give new users a quick (relatively speaking) introduction to the concepts behind MapServer. It is arranged into four sections with each section having one or more examples and increasing in complexity. Users can jump to any section at any time although it is recommended that absolute beginners work on the first three sections sequentially.

Section one focuses on basic MapServer configuration concepts such as layer and class ordering, using vector and raster data, projections and labeling. Section two provides examples on how to use HTML templates to create a simple interface for an interactive web mapping application. Section three introduces the use of HTML templates to provide a "query" interface. Finally, section four introduces some advanced user interface concepts.

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 http://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 your 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 web server and a MapServer CGI program (mapserv or mapserv.exe) installed in their systems. MapServer source code is available for download at https://mapserver.org/download.html. Documentations exist on how to compile and install MapServer--for UNIX users, please read the "MapServer UNIX Compilation and Installation HOWTO". Windows users can read the "MapServer Win32 Compilation and Installation HOWTO". In addition, Windows users can also download precompiled binaries from https://mapserver.org/download.html#binaries.

Windows, UNIX/Linux Issues
This tutorial was created in Linux/UNIX but should work with minimal changes on Windows platform. 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 this--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., "/projects/tutorial35/" is relative to "http://terrasip.gis.umn.edu/". Please read this for a few insights on URLs.

Another issue is that UNIX executable files don't require a .EXE or .COM extensions. They do in Windows. If you are using Windows, append .exe to all instances of "/cgi-bin/mapserv" or "/cgi-bin/mapserv74" to make it "/cgi-bin/mapserv.exe" or "/cgi-bin/mapserv74.exe".

Other Resources
Other documentations 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 several HOWTO documents--from getting started to using MapScript, a scripting interface for MapServer.

Installation Instructions | Go to the tutorial   |   Download the tutorial

Acknowledgements

Created by Pericles S. Nacionales
Maintained by Jeff McKenna, GatewayGeo
Last updated: 2021-11-19