Update 2016-07-31

For the latest installation instructions, please see the official QGIS Server documentation.

This post summarizes my notes about installing QGIS Server on Ubuntu, adding a QGIS project file to the server and using the WMS in an OpenLayers application.

Installation

First, it’s useful to figure out the Ubuntu version:

lsb_release -a

Since my server runs “lucid”, I add the following package sources to /etc/apt/sources.list (as described in the QGIS installation documentation)

deb http://qgis.org/debian lucid main
deb-src http://qgis.org/debian lucid main

Before we can install anything, we need to add the key and update the package list

gpg --keyserver keyserver.ubuntu.com --recv 1F9ADD375CA44993
gpg --export --armor 1F9ADD375CA44993 | sudo apt-key add -
sudo apt-get update

Now we can install QGIS Server and the necessary Apache package

sudo apt-get install qgis-mapserver libapache2-mod-fcgid

It never hurts to restart Apache :)

sudo /etc/init.d/apache2 restart

Let’s test the installation before we proceed. The GetCapabilities request should already work

http://10.101.21.28/cgi-bin/qgis_mapserv.fcgi?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities

Adding a QGIS project file

It’s time to add a QGIS project to our server. To do that, we move to the QGIS Server folder

cd /usr/lib/cgi-bin

where you should find qgis_mapserv.fcgi and wms_metadata.xml.
I’ve decided to have one folder for each project file. My first project is “vienna”.

sudo mkdir vienna
cd vienna

qgis_mapserv.fcgi and wms_metadata.xml can now be linked into this new folder

sudo ln -s ../qgis_mapserv.fcgi .
sudo ln -s ../wms_metadata.xml .

The only thing that’s missing anymore is a QGIS project file. It can be copied or linked into the folder. After restarting Apache, we should be good to go.

Let’s test the setup using “Add WMS Layer” in QGIS by adding the service URL such as

http://10.101.21.28/cgi-bin/vienna/qgis_mapserv.fcgi

and ticking “Ignore GetMap URI …” and “Ignore GetFeature URI …”.

After clicking “Connect”, all layers from the project file we added should get listed and we can select and load them.

QGIS Server can serve as many project files as you want. There are different ways to organize your server but I would simply add a new folder (like the “vienna” folder in this example) and link in the executable and project file.

Using QGIS Server WMS in OpenLayers

Of course QGIS Server doesn’t just talk to QGIS Desktop but to any other WMS client that conforms to the standard. One classic use case is to add the WMS layers to an OpenLayers application. This is rather simple but I’ll add it here for the sake of completeness:

I used to have a Geoserver WMS base layer in my application. The only lines of code that needed to be changed to migrate to QGIS Server were the service URL and the layer names.

wms = new OpenLayers.Layer.WMS(
    'roads', "http://10.101.21.28/cgi-bin/vienna/qgis_mapserv.fcgi",
    {
        layers: 'roads',
        format: 'image/png';
        bgcolor: '#fafafa'
    },
    {
        buffer: 1,
        isBaseLayer: true,
        graphicZIndex: 0,
    }
);

Standardized services are great!