| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# 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 now 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:

1. 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.

2. 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.

3. It is recommended that users of this tutorial read the Introduction to MapServer before proceeding with this tutorial.

4. 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 was created on 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:

    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 http://www.alistapart.com/articles/slashforward/ for a few insights on URLs.

### Executable

Another issue is that UNIX executable files don’t require a .EXE or .COM extensions, but they do in Windows. If you are using Windows, append .exe to all instances of “/cgi-bin/mapserv” or “/cgi-bin/mapserv50” to make it “/cgi-bin/mapserv.exe” or “/cgi-bin/mapserv50.exe”.

## Other Resources

Other documentation exist to give you better understanding of the many customizations MapServer offer. Please visit the MapServer documentation page at http://www.mapserver.org/documentation.html. There you will find several HOWTO documents, from getting started to using MapScript, a scripting interface for MapServer.

Back to Tutorial home | Proceed to Section 1