.. _configuration :
*************
Configuration
*************
.. note:: Before you start to tune your PyWPS installation, you can download
OpenGIS(R) Web Processing Service document (OGC 05-007r7) version
1.0.0 http://www.opengeospatial.org/standards/wps or later, for reference.
Setting up the PyWPS instance
=============================
PyWPS can be installed once on your server, but it be configured for many
WPS servers (instances). Each WPS server needs a set of processes (stored in
one directory) and a configuration file.
Processes are stored together as python programs in one directory as follows:
1 - create ``processes`` directory -- directory, where you store all
processes for particular PyWPS instance::
$ mkdir -p /usr/local/wps/processes
2 - copy template of the configuration file to some location, and
configure your PyWPS installation (see below)::
$ cp pywps-VERSION/pywps/default.cfg /usr/local/wps/pywps.cfg
$ $EDITOR /usr/locap/wps/pywps.cfg
3 - create any process(es) in the ``processes`` directory. You can start with
the example processes, stored in `pywps-VERSION/examples/processes`
directory. See :ref:`how-to-write-custom-process` for how to write
custom processes.::
$ cp pywps-VERSION/examples/ultimatequestionprocess.py /usr/local/wps/processes/
6 - Each process in the ``processes`` directory must be
registered in the `__init__.py` file. The file has to contain at
least::
__all__ = ["ultimatequestionprocess"]
Where ``__all__`` represents list of processes (file names) within the
``processes`` directory.
Accepted environment variables
------------------------------
The following environment variables are accepted by a PyWPS instance:
PYWPS_CFG
Configuration file location
PYWPS_PROCESSES
Directory, where the processes are stored
PYWPS_TEMPLATES
Templates directory (structure should be similar to
file:`pywps/Templates`)
Setting up the Web Server
-------------------------
PyWPS can run as `CGI `_ application or in
`mod_python `_ mode. CGI is easier to setup,
where mod_python is less demanding on server resources, since after the first
run, PyWPS and Python itself are loaded into memory.
PyWPS as CGI
............
CGI configuration is a simple appraoch, without any additional server configuration.
To configure PyWPS via CGI, copy the PyWPS CGI wrapper script to
your ``cgi-bin`` directory and edit the variables::
$ cp pywps/resources/pywps.cgi /usr/lib/cgi-bin
$ $EDITOR /usr/lib/cgi-bin/pywps.cgi
.. note:: Windows users must create a either a .bat file or Python wrapper.
This example is written as UNIX shell script.
.. note:: This script is to be used only via HTTP (with e.g. Apache). If you
want to run PyWPS from the command line, use `wps.py` directly.
Below is a sample wrapper::
#!/bin/sh
# Author: Jachym Cepicky
# Purpose: CGI script for wrapping PyWPS script
# Licence: GNU/GPL
# Usage: Put this script to your web server cgi-bin directory, e.g.
# /usr/lib/cgi-bin/ and make it executable (chmod 755 pywps.cgi)
# NOTE: tested on linux/apache
export PYWPS_CFG=/usr/local/wps/pywps.cfg
export PYWPS_PROCESSES=/usr/local/wps/processes/
/usr/local/pywps-VERSION/cgiwps.py
You can also configure HTTP environment variables using standard Apache
server configuration file (see :ref:`mod_python`) for example.
.. _mod_python :
PyWPS in mod_python
...................
Overall, PyWPS has better performance via mod_python. All necessary
libraries are pre-loaded into memory and response times should be
faster in some cases.
1 - Install necessary packages, on debian, it is `libapache2-mod-python`
2 - Configure Apache HTTP server (see `Mod Python documentation `_).
1 - Create python directory (preferably outside ``htdocs`` directory)::
$ mkdir /var/www/wps/
2 - Add this to your HTTP configuration file::
SetEnv PYWPS_PROCESSES /usr/local/wps/processes
SetEnv PYWPS_CFG /usr/local/wps/pywps.cfg
SetHandler python-program
PythonHandler pywps
PythonDebug On
PythonPath "sys.path+['/usr/local/pywps-VERSION/']"
PythonAutoReload On
or you can copy :file:`resources/.htaccess` to `/var/www/wps` --
depending on what level of access you are provided by your
system administrator.
3 - Copy :file:`resources/pywps.py` to :file:`/var/www/wps`
PyWPS configuration files
=========================
Configuration file for PyWPS can be located in several places. There are
global and local PyWPS configuration files. Local configurations override
global configurations.
Global PyWPS configuration files
--------------------------------
1. File :file:`/etc/pywps.cfg` (on Linux/Unix)
2. File :file:`/usr/local/pywps-VERSION/etc/pywps.cfg`, which means the
file :file:`pywps.cfg` in directory :file:`etc`, located in PyWPS
install location.
And one special file:
File :file:`/usr/local/pywps-VERSION/pywps/default.cfg`, which means the
file :file:`default.cfg` in directory :file:`pywps`, located in PyWPS
install location. This is the default configuration file.
.. note:: Never rewrite or remove this file. Use it only as template for
your custom configuration files.
Local PyWPS configuration file
------------------------------
The local configuration file is used for the particular PyWPS instance only. It
is the file, stored in :envvar:`PYWPS_CFG` environment variable. This can
be set either via web server configuration or with any wrapper
script (see :file:`resources/pywps.cgi` for example).
Make a copy of :file:`pywps/default.cfg` to
:file:`/usr/local/wps/pywps.cfg` and customize the file as per below.
Configuration of PyWPS instance
===============================
Several sections are in the configuration file. The sections
contain `key value` pairs of configuration options (see the example at the
end of this section). If you do not set these options, they will
be taken from the default configuration file.
WPS
---
The [wps] section contains general WPS instance settings, which are:
encoding
Language encoding (utf-8, iso-8859-2, windows-1250, \dots)
title
Server title
version
WPS version (1.0.0)
abstract
Server abstract
fees
Possible fees
constraints
Possible constraints
serveraddress
WPS script address: http://foo/bar/pywps.py or http://foo/bar/cgi-bin/pywps.cgi
keywords
Comma-separated list of keywords realted to this server instance
lang
Comma-separated list of supported server languages. Default is
'eng'.
Provider
--------
The [provider] section contains information about you, your organization and so on:
providerName
Name of your company
individualName
Your name
positionName
At which position you are working
role
What your role is
deliveryPoint
Street
city
City
postalCode
Postal code or Zip code
country
Country name
electronicMailAddress
E-mail address
providerSite
Web site of your organization
phoneVoice
Telephone number
phoneFacsimile
Fax number
administrativeArea
State, province, territory or administrative area
hoursofservice
Hours of service to contact the provider
contactinstructions
Instructions on how to contact the provider
Server
------
The [server] section contains server settings, constraints, safety configuration and so on:
maxoperations
Maximum number of parallel running processes. If set to 0, then there is no limit.
maxinputparamlength
Maximum length of string input parameter (number of characters).
maxfilesize
Maximum input file size (raster or vector). The size can be determined as follows: 1GB, 5MB, 3kB, 1000b.
tempPath
Directory for temporary files (e.g. :file:`/tmp/pywps`). PyWPS will
create temporary directories in this directory, and after the calculation
is performed, they *should* be deleted again.
outputPath
Path where output files are stored on the server.
This should point to the `outputUrl` parameter (described below). For
example http://foo/bar/wpsputputs. If outputPath starts with ftp:// it's assumed that FTP support shall be used.
outputUrl
Url where the outputs are stored for client access. On
Debian, it would be for example :file:`/var/www/wpsoutputs`
ftplogin
FTP user login, if empty, anonymous login is used.
.. note:: FTP support is activated by ftp:// in outputPath
ftppasswd
FTP user password
ftpport
Default FTP port 21 is used if variable not defined.
debug
true/false - makes the logs for verbose
.. note:: This option is not used so wildly, as it should maybe be.
.. note:: Deprecated since 3.2. Use logLevel instead
processesPath
path to your processes. Default is pywps/processes.
.. note::
You can also set the :envvar:`PYWPS_PROCESSES` environment
variable with the same result, as described earlier on this page.
logFile
(since 3.0.1) File where all PyWPS logs go to. If not
set, default error.log from Web Server configuration is used.
Sometimes, this can cause problem for the asynchronous calls.
logLevel
(since 3.2) one of DEBUG, INFO, WARNING, ERROR and CRITICAL,
default is INFO
GRASS
-----
The [grass] section is specifically for GRASS GIS settings (optional):
path
:envvar:`PATH` environment variable, e.g. :file:`/usr/lib/grass/bin:/usr/lib/grass/scripts`
addonPath
:envvar:`GRASS_ADDONS` environment variable
version
GRASS version
gui
Should be "text"
gisbase
Path to GRASS :envvar:`GIS_BASE` directory (:file:`/usr/lib/grass`)
ldLibraryPath
Path of GRASS Libs (:file:`/usr/lib/grass/lib`)
gisdbase
Full path to GRASS database directory, where *Locations* are stored (:file:`/home/foo/grassdata`)
.. note::You do not have to setup
this variable in the configuration file globaly. You can use
`grassLocation` attribute while calling the
`__init__` method of Process class, while process
initialization. See section :role:`Processesprocesses for more details.
Configuration file example
==========================
::
[wps]
encoding=utf-8
title=PyWPS Server
version=1.0.0
abstract=See http://pywps.wald.intevation.org and http://www.opengeospatial.org/standards/wps
fees=None
constraints=none
serveraddress=http://localhost/cgi-bin/wps
keywords=GRASS,GIS,WPS
lang=eng
[provider]
providerName=Your Company Name
individualName=Your Name
positionName=Your Position
role=Your role
deliveryPoint=Street
city=City
postalCode=000 00
country=eu
electronicMailAddress=login@server.org
providerSite=http://foo.bar
phoneVoice=False
phoneFacsimile=False
administrativeArea=False
[server]
maxoperations=3
maxinputparamlength=1024
maxfilesize=3mb
tempPath=/tmp
processesPath=
outputUrl=http://localhost/wps/wpsoutputs
outputPath=/var/www/wps/wpsoutputs
debug=true
logFile=/var/log/pywps.log
[grass]
path=/usr/lib/grass/bin/:/usr/lib/grass/scripts/
addonPath=
version=6.2.1
gui=text
gisbase=/usr/lib/grass/
ldLibraryPath=/usr/lib/grass/lib
gisdbase=/home/foo/datagrass
Notes for Windows users
=======================
Windows users do have to adjust their paths to what is standard on this
platform. E.g. instead of using ":" as delemiter ";" is supposed to be used.
Also usage of slash "/" and backslash "\\" can be tricky.
Generally speaking, it's good to start by installing GRASS (if needed) and all
the required geospatial packages using `OSGeo4W tool `_.
Having GRASS and PyWPS is possible and was successfuly tested. You have to
adjust especially PATH variable. Example of relevant configuration parts
follows: ::
[server]
maxoperations=30
maxinputparamlength=1024
maxfilesize=10mb
tempPath=c:\\\\tmp
processesPath=
outputUrl=http://localhost/tmp/wpsoutputs
outputPath=c:\OSGeo4W\apache\htdocs\tmp\wpsoutputs\
debug=true # deprecated since 3.2, use logLevel instead
logFile=
logLevel=INFO
[grass]
path=c:\\\\osgeo4w/apps/grass/grass-7.0.0/lib;c:\\\\osgeo4w/apps/grass/grass-7.0.0/bin;c:\\\\c/Users/jachym/AppData/Roaming/GRASS7/addons/bin;c:\\\\usr/bin;c:\\\\osgeo4w/bin;c:\\\\c/Windows/system32;c:\\\\c/Windows;c:\\\\c/Windows/WBem;c:\\\\usr/bin;c:\\\\osgeo4w/apps/Python27/Scripts
addonPath=
version=7.0.0
gui=text
gisbase=c:\\\\OSGeo4W\\\\apps\\\\grass\\\\grass-7.0.0
ldLibraryPath=c:\OSGeo4W\apps\grass\grass-7.0.0\lib
gisdbase=c:\Users\jachym\src\vugtk\grassdata\
home=c:\Users\jachym
FOr the configuration of Apache web server, you can directly use `wps.py` binary
from the root of PyWPS source code and use it. Example of relevant httpd.conf
file follows (it can of course be used on Unix as well)::
# wps.py was copied from pywps-source/wps.py
Alias /wps C:\OSGeo4W/bin/wps.py