History

About QGIS Server

The reference manual for QGIS Server is now available on the official manual: http://docs.qgis.org/testing/en/docs/user_manual/working_with_ogc/ogc_server_support.html

QGIS Server provides a web map service (WMS) using the same libraries as the Quantum GIS (QGIS) desktop application.
Maps and print templates created in QGIS desktop can be published as web maps simply by copying the QGIS project file into the server directory. The resulting web maps look exactly the same as in the desktop.
QGIS Server is usually run as CGI/FastCGI module within the Apache Webserver.

Core Features

  • Web Map Service (WMS) implementation
  • Built-in PDF output
  • WYSIWYG map creation with QGIS
  • Advanced cartographic symbolisation
  • Supports Styled Layer Descriptor (SLD)
  • Identification of features and display of attribute data

FOR DETAILED CONFIGURATION NOTES, PLEASE ALSO READ THE README SUPPLIED WITH THE QGIS WEB CLIENT!

Webserver configuration

Debian/Ubuntu Linux

To setup QGIS Server with Apache 2 mod_fastcgi, the following packages are required:

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

Note that libapache2-mod-fcgid and libapache2-mod-fastcgi are different packages and require different configurations.

Enable fcgi in apache2: 

a2enmod fcgid

Enable /cgi-bin in apache2: 

a2enconf serve-cgi-bin

Restart apache2:

sudo service apache2 restart

Using the default configuration, QGIS Server should answer a GetCapabilities request from here:

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

Centos

Centos 6

  • In the following commands, the packages are given for a x86_64 architecture, and :
$ before the command means you can run it as a standard user
# before the command means you must have root rights
  • Add the EPEL repository
$wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-7.noarch.rpm
#rpm -Uvh epel-release-6-7.noarch.rpm
  • Add the ELGIS repositories
    $wget http://elgis.argeo.org/repos/6/elgis-release-6-6_0.noarch.rpm
#rpm -Uvh elgis-release-6-6_0.noarch.rpm
  • Install QGIS Server
#yum install qgis*
# this will install all the Qgis libraries, QGIS Desktop included.
# I you only need QGIS Server, use the following instead:
#yum install qgis-mapserver.x86_64

Mac OS X

QGIS Server uses the system Apache 2 with mod_fastcgi in a default configuration, on OS X 10.5 (Leopard) and OS X 10.6 (Snow Leopard). mod_fastcgi and the fastcgi library were dropped in OS X 10.7 (Lion).

The QGIS Server fastcgi will be installed within the QGIS application package as QGIS.app/Contents/MacOS/fcgi-bin/qgis_mapserv.fcgi (note: this could change in the future). The following instructions assume a default installation in /Applications.

The method used depends on whether the mapserver is running on the standard client OS X ("OS X") or OS X Server.

A handy tool for both is TextWrangler, but you can use any text editor that can edit and save files that need administrator permissions.

Installing libfcgi and mod_fastcgi

For systems without them.

The install instructions have instructions for installing libfcgi. mod_fastcgi will be installed instead of one of the other variants for simplicity and consistency across systems. If you want to use one of the other Apache fastcgi modules, you'll have to find install instructions and adjust configuration.

Download apache_mod_fastcgi from:

http://opensource.apple.com/

Find it in the Mac OS X 10.6.8 sources. Apple's copy has some important fixes to support Apache 2.2 as provided in OS X.

Double-click the source tarball to unpack it, then in a Terminal cd to the mod-fastcgi inside the source folder and:

For MacOs 10.8 (mountain Lion) and you are using the Apple installed apache -- there is a bug in 10.8 in the apache build env which breaks the compilation of any modules . The fix is to put a symlink before doing the make below.

 sudo ln -s /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/ /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain

cp Makefile.AP2 Makefile
make top_dir=/usr/share/httpd
sudo make top_dir=/usr/share/httpd install

Enable mod_fastcgi

On OS X, edit /etc/apache2/httpd.conf. Find the line starting with "#LoadModule fastcgi_module" (it may or may not have the leading "#"). Remove the "#" at the beginning of the line, if present. Save and close the file.

On OS X Server, use the Server Admin app. Select Web under your server, then Settings->Modules. Find fastcgi_module in the module list and check the box to enable it. Click the Save button.

You could also edit /etc/apache2/httpd.conf the same as for OS X, since the next can't be done from Server Admin.

Configure mod_fastcgi

On OS X, create a new text file /etc/apache2/other/qgis-mapserver.conf with the content:

<IfModule mod_fastcgi.c>
  FastCgiConfig -appConnTimeout 60 -idle-timeout 60 -init-start-delay 1 -minProcesses 2 -maxClassProcesses 20 -startDelay 5
  AddHandler fastcgi-script .fcgi
  Alias /qgis-mapserv/ /Applications/QGIS.app/Contents/MacOS/fcgi-bin/
  <Directory /Applications/QGIS.app/Contents/MacOS/fcgi-bin/>
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
  </Directory>
</IfModule>

If you already installed MapServer (the KyngChaos package includes a fastcgi configuration as of v5.6.5-2), then just add the lines above from "Alias" to "</Directory>" to /etc/apache2/other/mapserv_fcgi.conf.

For OS X Server, edit /etc/apache2/httpd.conf. Add the above configuration to the end of the file. Here also, if you have installed MapServer, there should be a mod_fastcgi block, so you just need to add the QGIS stuff to it. Save and close.

Restart Apache and Test

Restart the web server.

The simplest way on both OS X and OS X Server is to type in a Terminal:

 sudo apachectl graceful

Test by opening Safari and browsing to:

 http://localhost/qgis-mapserv/qgis_mapserv.fcgi?

You should get a message "Configuration file problem". This is good, QGIS Server is running, but no map file was given.

Windows

For a recent installation HOWTO see e.g. http://underdark.wordpress.com/2012/04/06/qgis-server-on-windows7-step-by-step/

0. Pre-notes
Working on/in windows means for me like working with ten thumbs on two left hands -- or:
I am not a windows expert! And normally I even do not have easy access to any winbox. So this howto explains
how I got QGIS server up and running but might not always show the ideal way.

If I placed something in "[]" this means that you have to use this as a variable and replace this by your specific keywords.

So, let's start....

1. Download the OsGeo4W-Installer
http://download.osgeo.org/osgeo4w/osgeo4w-setup.exe

2. Execute the installer, use the settings below:
(maybe the wording differs a little bit, as I translated this from German, I do not have an English winbox for testing, so I didn't see the English naming used by the installer)

   -> advanced installation (3. possibility)
   -> install from web (1. possibility)
   -> root-directory c:\OSGeo4W, all users
   -> leave the local-package directory as is or change it
   -> choose web-access due to your lan
   -> choose the following packages (don't care about dependencies, the installer does this automatically):
      - Desktop: Qgis
      - Web: Apache Webserver
                 QGIS-Server

3a. Apache (2.2.14-4 from OSGeo4W) does not have any default IP/port set and it fails to start. Edit the file

    c:/osgeo4w/apache/conf/httpd.conf

and change
   Listen @apache_port_number@

to your needs, for example, to listen on port 80,use
   Listen 80

Start apache (e.g. settings-panel -> services -> apache -> start.
Now you should be able to open default Apache web page in web browser (using http://127.0.0.1/ or http://localhost/ on local computer)

3b. In the moment (July 2011; this was not necessary with Apache 2.2.14-4 and QGIS Server 1.7.1-2 - October 20 2011 on XP) QGIS on windows seems not to work as FastCGI, so edit the file

    c:/osgeo4w/httpd.d/httpd_qgis.conf:

3b1. Change the line

LoadModule fcgid_module modules/mod_fcgid.so

to
LoadModule cgi_module modules/mod_cgi.so

3b2. Change the three references of 

DefaultInitEnv
to 
SetEnv
Using the DefaultInitEnv threw an error that it was an unknown option because of a misspelling or some module was not included. This occurred on my 64-bit Win 7 desktop.

3b3. In this section:

  <Directory "C:\OSGeo4W/apps/qgis/bin/">
    SetHandler fcgid-script
    Options ExecCGI
    Order allow,deny
    Allow from all
  </Directory>

change the SetHandler to this:

 {...}
   #SetHandler fcgid-script
    SetHandler cgi-script
 {...}

Restart apache (e.g. settings-panel -> services -> apache -> restart)

3c. If after restarting Apache and you get an error trying to go to the URL http://localhost/qgis/qgis_mapserv.fcgi.exe?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities, you may need to move some libraries into your qgis area. Copy all of the DLL libraries from 

C:/OSGeo4w/bin
to 
C:/OSGeo4W/apps/qgis/bin
Not sure if all the libraries are needed but copying all of them over fixed the error.

3d. If you do not want to use the osgeo-apache and already have your own
apache running, just create a directory in the apache-dir, e.g.

 "apache/httpd.d/"

and copy the httpd_qgis.conf file into this directory, then add the following section to the httpd.conf of your apache. Place this at the end of the
config-file and ensure bot to be in any subsection (subsections appear like
this <[sectionsname]> and end with 

 # parse other apache conf files
 include "C:\[YOURPATHTOYOURAPACHEINSTALLATION]\httpd.d\httpd_*.conf"

Restart apache (e.g. settings-panel -> services -> apache -> restart)
You also might change the installation directory of the QGIS server by
editing the pathes in the httpd_qgis.conf-file.

! Always restart Apache after changing anything on the apache-config (or
restart your complete server as you might be used to ;-) )

4. In my installation the link to the required *.dll's did not work (again, this was not necessary with Apache 2.2.14-4. - October 20 2011 on XP). There are required *.dlls in the folder


 c:/osgeo4w/apache/bin/

I copied all *.dll's from there to my qgis-server folder:

 c:/osgeo4w/apps/qgis/bin/

I am sure there is a better way, either linking the *.dll's to apache OR copy them to the c:/windows/system32/ directory,
but as I am not a windows expert, I choosed the quick&dirty way, which also works.

I also tried to find the really used dll's by double-clicking on the qgis_mapserv.fcgi.exe, but this is awful as these are many.

5. Create a QGIS project (e.g. world.qgs), save it e.g. to "c:/myprojects/" and call the GetCapabilities document by sending this request through your browser:

http://localhost/qgis/qgis_mapserv.fcgi.exe?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities&map=c:/myprojects/world.qgs

A capabilities-XML should appear. If so, congratulations, try your new QGIS server by calling a getMap-request:

http://localhost/qgis/qgis_mapserv.fcgi.exe?SERVICE=WMS&VERSION=1.3.0&SRS=EPSG:4326&REQUEST=GetMap&map=c:/myprojects/world.qgs&BBOX=-36.215710,6.817432,-9.700450,58.551008&WIDTH=500&HEIGHT=1000&LAYERS=world_countries&FORMAT=image/png

Be sure to have your correct layername(s) in the "&LAYER=[YOURLAYERNAME]"-Tag in the URL above.

You'll find them in the capabilities in the subsection <layer> in the subtag <name>[YOURLAYERNAME]</name> - please use the <name> not the title!

WARNING: the project file is not reloaded until you restart Apache!!!

Now you are ready to go. In the following I explain howto update and give some more notes from my experience.

6. Update QGIS-Server to nightly-built

In order to get the newest QGIS-builts also use the osgeo4w installer. First backup your httpd_qgis.conf-file, then run the osgeo4w-setup.exe again.
In the desktop-section now choose "QGIS nightly builts" (yes, Desktop - they include also the newest qgis_mapserv.fcgi.exe!!)

Go ahead as described in top 1.

Afterwards you'll probably have a new qgis-setup. In the source-files you'll find the brand new qgis_mapserv.fcgi.exe in the qgis-binary folder.
Copy this to the c:/osgeo4w/apps/qgis/bin-directory and test. I do not know, if probably any of the dll-files have changed, so if this does not work,
you might copy the dll's again as discussed above in top 4.

7. some notes
- avoid blanks in any names (project-files) and names of layers (not the titles!) as this is transported via URL and might cause problems
- in my experience it doesn't matter whether you use "/" or "\" in paths, except the following point:
- if data and/or project files are on a network-directory, which is mounted as e.g. disk "r:\" under windows, change the access to the Uniform Naming Convention (UNC)

  (see also: http://en.wikipedia.org/wiki/Uniform_Naming_Convention#Uniform_Naming_Convention)

which e.g. leads from "r:\[YOURPATH]\" to "\\[YOURINTERNALSERVERID]\[YOURPATH]"

You might change this by search and replace directly in the *.qgs-file or
by replacing it in the QGIS gui when adding a layer.
QGIS will accept this pathes as well and will not change this when
re-opening the project.

8. Have fun and please report comments on this HowTo and on QGIS Server!

   Report either to the list or to me ([email protected])

9. User comments (untested yet)

06. sept. 2011: "thanks for the nice QGIS Server tutorial (http://www.qgis.org/wiki/QGIS_Server_Tutorial)!
I configured QGIS Server under Windows, but in contrast to step 4 of the tutorial I had to copy all *.dlls from the C:\OSGeo4W\bin directory (not from C:\OSGeo4W\apache\bin) so that it worked. Before that, I had to install the "fcgi: Fast CGI Library" from the OSGeo4W setup, because these *.dlls were missing as well. Maybe you can add/change this in your tutorial."

QGIS Server configuration

Usefull variables for the configuration of Apache mod_fcgid (/etc/apache2/mods-enabled/fcgid.conf)
  • FcgidIOTimeout: Application timeout in seconds.
  • FcgidMaxProcessesPerClass: Maximum number of processes that can be created by the fcgid module
  • FcgidMinProcessesPerClass: Minimum number of processes which are kept alive by the fcgid module

More options: see http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html

QGIS project file WMS parameters

General

  • WMSRestrictedLayers
  • WMSComposerList

On layer level

  • excludeAttributesWMS
  • excludeAttributesWFS

Capabilities

  • WMSServiceTitle
  • WMSServiceAbstract
  • WMSOnlineResource
  • WMSContactPerson
  • WMSContactOrganization
  • WMSContactPhone
  • WMSContactMail
  • WMSFees
  • WMSAccessConstraints
  • WMSKeywordList

FeatureInfo output

(Not yet configurable in Desktop)

  • WMSFeatureInfoDocumentElement: give different feature info root element name (default: GetFeatureInfoResponse)
  • WMSFeatureInfoDocumentElementNS: set namespace for feature info root element (default: none)
  • WMSFeatureInfoSchema: add link to schema to root element
  • WMSFeatureInfoAliasLayers / WMSFeatureInfoLayerAliases: possibility to define aliases for layernames in GetFeatureInfo output
  • WMSInfoFormatSIA2045: Feature output format in SIA2045 schema (default: disabled)

QGIS Web Client

QGIS Web Client is generic Web GIS frontend for WMS servers, supporting all additional features of QGIS Server like highlighting and printing.

Source and documentation is available at https://github.com/qgis/qgis-web-client

Extensions to WMS

QGIS supports the WMS 1.3 specification. Additionally, it supports some additional optional parameters and requests:

Map parameter

Similar to UMN mapserver, the map parameter can be used to specify the path to the QGIS projectfile. If not specified, QGIS searches for .qgs files in the directory where the server executable is located.

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?MAP=/home/user/mymap.qgs&...

DPI parameter

The dpi parameter can be used to specify the requested output resolution.

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?....&DPI=300&...

FILTER parameter

(Available in QGIS 1.8 and above)

Subsets of layers can be selected with the FILTER parameter. Syntax is basically the same as for the QGIS subset string. However, there are some restrictions to avoid SQL injections into databases via QGIS server:

  • Text strings need to be enclosed with quotes (single quotes for strings, double quote for attributes)
  • A space between each word / special character is mandatory
  • Allowed Keywords and special characters are 'AND','OR','IN','=','<','>=','>','>=','!=*,'(',')'
  • Semicolons in string expressions are not allowed

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?REQUEST=GetMap&LAYERS=mylayer1,mylayer2&FILTER=mylayer1:"OBJECTID" = 3;mylayer2:'text' = 'blabla'&....

Note that it is possible to make attribute searches via GetFeatureInfo and leave away the X/Y parameter if a FILTER is there. QGIS server then returns info about the matching features and generates a combined bounding box in the xml output

SELECTION parameter

(Available in QGIS 1.8 and above)

Vector features can be selected by passing comma separated lists with feature ids in GetMap and GetPrint.

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?REQUEST=GetMap&LAYERS=mylayer1,mylayer2&SELECTION=mylayer1:3,6,9;mylayer2:1,5,6&...

OPACITIES parameter

Opacity can be set on group/layer level, range is 0 (fully transparent) to 255 (fully opaque).

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?REQUEST=GetMap&LAYERS=mylayer1,mylayer2&OPACITIES=125,200

GetPrint request

QGIS server has the capability to create print composer output as pdf or pixel format. Print composer windows in the published project are used as templates. In the GetPrint request, the client has the possibility to specify parameters of the contained composer maps and labels.

Example:

The published project has two composer maps. In the GetProjectSettings response (not in GetCapabilities response), they are listed as possible print templates:

<WMS_Capabilities>
...
<ComposerTemplates xsi:type="wms:_ExtendedCapabilities">
<ComposerTemplate width="297" height="210" name="Druckzusammenstellung 1">
<ComposerMap width="171" height="133" name="map0"/>
<ComposerMap width="49" height="46" name="map1"/></ComposerTemplate>
</ComposerTemplates>
...
</WMS_Capabilities>

The client has now the information to request a print output:
http://myserver.com/cgi/qgis_mapserv.fcgi?...&REQUEST=GetPrint&TEMPLATE=Druckzusammenstellung 1&map0:EXTENT=xmin,ymin,xmax,ymax&map0:ROTATION=45&FORMAT=pdf&DPI=300

Parameters in the GetPrint request are:
  • <map_id>:EXTENT gives the extent for a composer map as xmin,ymin,xmax,ymax.
  • <map_id>:ROTATION map rotation in degrees
  • <map_id>:GRID_INTERVAL_X, <map_id>:GRID_INTERVAL_Y Grid line density for a composer map in x- and y-direction
  • <map_id>:SCALE Sets a mapscale to a composer map. This is usefull to ensure scale based visibility of layers and labels even if client and server may have different algorithms to calculate the scale denominator
  • <map_id>:LAYERS, <map_id>:STYLES possibility to give layer and styles list for composer map (usefull in case of overview maps which should have only a subset of layers)

GetLegendGraphics

Several additional parameters are available to change the size of the legend elements:
  • BOXSPACE space between legend frame and content (mm)
  • LAYERSPACE versical space between layers (mm)
  • LAYERTITLESPACE vertical space between layer title and following items (mm)
  • SYMBOLSPACE vertical space between symbol and following item (mm)
  • ICONLABELSPACE horizontal space between symbol and label text (mm)
  • SYMBOLWIDTH width of the symbol preview (mm)
  • SYMBOLHEIGHT height of the symbol preview (mm)
These parameters change the font properties for layer titles and item labels
  • LAYERFONTFAMILY / ITEMFONTFAMILY font family for layer title / item text
  • LAYERFONTBOLD / ITEMFONTBOLD 'TRUE' to use a bold font
  • LAYERFONTSIZE / ITEMFONTSIZE Font size in point
  • LAYERFONTITALIC / ITEMFONTITALIC 'TRUE' to use italic font
  • LAYERFONTCOLOR / ITEMFONTCOLOR Hex color code (e.g. #FF0000 for red)
  • LAYERTITLE / RULELABEL (from QGIS 2.4) set them to 'FALSE' to get only the legend graphics without labels
Contest based legend. These parameters let the client request a legend showing only the symbols for the features falling into the requested area
  • BBOX the geographical area for which the legend should be built
  • CRS / SRS the coordinate reference system adopted to define the BBOX coordinates
  • WIDTH / HEIGHT if set these should match those defined for the GetMap request, to let QGIS Server scale symbols according to the map view image size.

Contest based legend features are based on the UMN MapServer implementation: http://www.mapserver.org/development/rfc/ms-rfc-101.html

GetProjectSettings

This request type works similar as GetCapabilities, but it is more specific to QGIS and allows for a client to read additional information which is not available in the GetCapabilities output:
  • initial visibility of layers
  • information about vector attributes and their edit types
  • information about layer order and drawing order
  • list of layers published in WFS

DXF Export

Starting with QGIS 2.11 (QGIS master as of 2015-07) it is now possible to export layers in the DXF format using the GetMap Request. Only layers that have read access in the WFS service are exported in the DXF format. Here is a valid REQUEST and a documentation of the available parameters:

http://your.server.address/wms/liegenschaftsentwaesserung/abwasser_werkplan?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&LAYERS=Haltungen,Normschacht,Spezialbauwerke&STYLES=&CRS=EPSG%3A21781&BBOX=696136.28844801,245797.12108743,696318.91114315,245939.25832905&WIDTH=1042&HEIGHT=811&FORMAT=application/dxf&FORMAT_OPTIONS=MODE:SYMBOLLAYERSYMBOLOGY;SCALE:250&FILE_NAME=werkplan_abwasser.dxf

Parameters:

  • FORMAT=application/dxf
  • FILE_NAME=yoursuggested_file_name_for_download.dxf
  • FORMAT_OPTIONS=see options below, key:value pairs separated by Semicolon

FORMAT_OPTIONS Parameters:

  • SCALE:scale to be used for symbology rules, filters and styles (not an actual scaling of the data - data remains in the original scale)
  • MODE:NOSYMBOLOGY|FEATURESYMBOLOGY|SYMBOLLAYERSYMBOLOGY corresponds to the three export options offered in the QGIS Desktop DXF export dialogue
  • LAYERSATTRIBUTES:yourcolumn_with_values_to_be_used_for_dxf_layernames - if not specified, the original QGIS layer names are used

External resources

Here are a few links with additional information:

http://wiki.catalystframework.org/wiki/deployment/apache_fastcgi#FastCGI_at_Root_and_Somewhere_Else

http://www.sourcepole.com/web-based-printing-with-qgis-server

http://karlinapp.ethz.ch/qgis_wms/index.html

http://karlinapp.ethz.ch/qgis_wms/giscience2010/

http://linfiniti.com/2010/08/qgis-mapserver-a-wms-server-for-the-masses/

Using OpenLayers with QGIS server:
http://live.osgeo.org/en/quickstart/openlayers_quickstart.html

qgis-web-client.jpeg (159 KB) Tim Sutton, 2012-02-01 05:15 AM

qgis-web-client.jpeg (46.7 KB) Tim Sutton, 2012-02-01 05:38 AM