Mapserver

The N00B guide for installing Mapserver and its libraries on a Virtual Private Server using Linux

You can also use this installation guide for reference in your own installation: it doesn't have to specifically be a VPS.

Short overview:

• use putty to connect to your server
• read the helpfiles for instructions (readme, install etcetera)
• standard dir for installing stuff: "/usr/local/". Transfer the source distributions (as a tar.gz or tar.bz2 file) there using your ftp program, or download them using linux wget command
• keep it simple: often use the standard settings unless you really need otherwise
• linux commands: http://www.ss64.com/bash/

Installing mapserver on a VPS

I'm using a Virtual Private Server, as I can't afford a complete server. VPS offers you root access and installation capabilities, so you can install (almost) everything you want! My hoster already has an install application procedure, so I could install some standard programs with a single click. It's usefull to install the following already:

• PHP
• GNU Compiler Collection (otherwise compiling source code won't work!)

Other applications you can choose for yourself. I prefer using MySQL and phpMyAdmin as well. They can also be installed using the source code files and the installation commands. They often require some extra configuration though.

Anyway, Mapserver requires some extra libraries, and some are optional. Browse through the mapserver website to check which libraries you think are useful. Download the mapserver application there as well. If you've never used the libraries before, they all have very strange names... Here a list:

Mapserver requires:

• libpng: PNG reference library
• freetype: Fonts library
• GD: Rendering images library
• zlib: Data compression library

Check the libraries list at one of the howto's of Mapserver for more libraries. You definitely should do this and NOT skip this part, because you definitely want some extra libraries. I did.

1. So first copy all the tar.gz files to the "/usr/local/" directory. This can be done using your ftp. You can also download them directly using "wget URL". I recommend downloading the tar.gz files to your computer and then use FTP to the server: this allows you to look into the tar.gz files and read the installation instructions.
   
   
2. Connect to your server using Putty or any other SSH client. Simply fill in your website address and use SSH to connect, and putty will ask you to input your username and password.
   
   
3. Next to do is to unpack the files. You can unpack each file and install this one immediately, or unpack all files and then do the installation sequence for each unpacked file. Browse to the directory "/usr/local/" using "cd .." and "cd DIR" and you'll get there. The command for unpacking tar.gz is "tar -xzf FILE" and tar.bz2 is "tar -xzf FILE". The file will be unpacked to the current directory. Inside the tar often a directory with the same name as the tar-file resides, so you can then browse to that directory to start the installation.
   
   
4. Install the libraries. Sometimes there's a special order: if you want special image libraries and GD, first install the image libraries and then GD. Libraries always come first. Check inside the tar.gz for the readme and/or install file with explanation on how to install. The most simple install which works for a lot of libraries (don't use this for every library, trial and error can result in wrong installations) are the following commands: "cd UNPACKDIR" "./configure" "make clean" "make" "make install" "cd ..". Sometimes the configure commands need extra flags, like "./configure --FLAGNAME=FLAGVALUE". For this, check each readme files if you need flags or not.
   
   On my own install, I used the following Linux code:
   
   • Browse to /usr/local (using "cd .." and "cd DIR")
   • Unpack one tar file ("tar -xzf FILE.tar.gz" or "tar -xjf FILE.tar.bz2")
   • cd DIR
   Then start installation:
   • ./configure
   • make clean
   • make
   • make install
   • cd ..
   This installation code can be used for almost all libraries. I used this code for: freetype, jpegsrc, zlib, tiff, ligbeotiff, gd, curl, proj and geos. For gdal I used "./configure --with-ogr" instead of the standard "./configure".
   
   The libpng requires zlib and therefore you first have to install zlib before installing libpng. Also, the directory name might be giving errors (as there's a version number in it). Therefore, before installing zlib, execute (make sure you are currently in /usr/local/):
   
   • rm zlib-xxxx.tar.gz
   • rm libpng-xxxx.tar.gz
   • mv zlib* zlib
   • mv libpng* libpng
   • cd libpng
   Now you can execute the installation sequence as mentioned above.
   
   
5. Allright, now all libraries are installed, it's time for installing mapserver. Best to do this, is using the extra configure options, and not to use the standard installation procedure. Execute the ./configure command with the extra options you can find in the CONFIGURE.README file in the tar file. Use "\" (the backslash) to continue a command on the next line. As an example I'll give the code I executed here (don't simply copy paste!):
   
   • ./configure \
     --with-jpeg \
     --with-gd \
     --with-freetype \
     --with-zlib \
     --with-png \
     --with-pdf \
     --without-eppl \
     --with-proj=/usr/local/proj-4.5.0/ \
     --with-geos=/usr/local/bin/geos-config \
     --with-gdal=/usr/local/bin/gdal-config \
     --with-ogr \
     --with-wfs \
     --with-wcs \
     --with-wmsclient \
     --with-wfsclient \
     --with-curl-config=/usr/local/bin/curl-config \
     --with-php=/usr/local/php/
   
   If you use GDAL and OGR, you don't have to specify the path for OGR again. The php directory sometimes can be located in the \usr\include\ directory as well. Then, after executing this large configure command, execute
   
   • make
   Notice that the cgi-bin directory, the program directory and the php library directory might be different on your system. Please check this and change it to the correct directories before executing the following commands:
   
   • cp mapserv /var/www/cgi-bin/
   • cp mapserv /usr/bin/
   • cp shp2img /usr/bin/
   • cp shptree /usr/bin/
   • cp tile4ms /usr/bin/
   • cp mapscript/php3/php_mapscript.so \
     /usr/local/php/lib/php/extensions/no-debug-non-zts-20060613/


6. You're done! Well, if you pass the test... so it's time to check if it works. The first test in linux:
   
   • mapserv -v
   It should list no errors, but the version number and some information about the mapserver installation.
   
   Next step is to test the cgi executable: go to http://www.yourdomain.com/cgi-bin/mapserv. If the mapserver is installed correctly, it should say "No query information to decode. QUERY_STRING not set.". This means a good installation.
   
   If you also supplied the php option (as you know, this was not necessary), you can test if the Mapscript (Mapserver's script for PHP) works. Use the following simple php script to test this:
   <?php
dl("php_mapscript.so");
phpinfo();
?>
It should list the extension Mapscript, see the image as an example.
   
   
   
   You want to know for sure if the mapscript is loaded? You can use a second check by creating a php with the following code:
   <?php
dl("php_mapscript.so");
if (extension_loaded('mapscript')) {
echo "Mapscript loaded";
} else {
echo "Mapscript not loaded";
}
?>
There it should say, of course, "Mapscript loaded". If not, there must be something wrong... you can use the linux command test "mapserv -v" or "mapserv" (which always gives an error saying it can't be executed in the linux environment) to see where the error lies. Unfortunately, as every system is different, I don't have an extended view of where your error can be in... you have to find that for yourself of use forums for this.
   
   

Always use more resources on the internet, they will help you a lot. I also hope this instruction was helpful to you.

Links

Linux commands
Putty
Mapserver for new users
Installing on UNIX - usefull for the library listing
Installation of Mapserver from scratch - linux code
Installing Mapscript PHP