Installation

This tutorial guides you to the MapProxy installation process on Unix systems. For Windows refer to Installation on Windows.

This tutorial was created and tested with Debian 5.0/6.0 and Ubuntu 10.04 LTS, if you’re installing MapProxy on a different system you might need to change some package names.

MapProxy is registered at the Python Package Index (PyPI). If you have installed Python setuptools (python-setuptools on Debian) you can install MapProxy with sudo easy_install MapProxy.

This is really easy but we recommend to install MapProxy into a virtual Python environment. A virtualenv is a self-contained Python installation where you can install arbitrary Python packages without affecting the system installation. You also don’t need root permissions for the installation.

Read about virtualenv if you want to know more about the benefits.

Create a new virtual environment

virtualenv is available as python-virtualenv on most Linux systems. You can also download a self-contained version:

wget https://github.com/pypa/virtualenv/raw/1.6.1/virtualenv.py

To create a new environment with the name mapproxy call:

virtualenv mapproxy
# or
python virtualenv.py mapproxy

You should now have a Python installation under mapproxy/bin/python. You need to either prefix all commands with mapproxy/bin, set your PATH variable to include the bin directory or activate the virtualenv with:

source mapproxy/bin/activate

This will change the PATH for you and will last for that terminal session.

Install Dependencies

MapProxy is written in Python, thus you will need a working Python installation. MapProxy works with Python 2.5, 2.6 and 2.7, which should already be installed with most Linux distributions.

MapProxy has some dependencies, other libraries that are required to run. There are different ways to install each dependency. Read Dependency details for a list of all required and optional dependencies.

Installation

On a Debian or Ubuntu system, you need to install the following packages:

sudo aptitude install python-imaging python-yaml libproj0

To get all optional packages:

sudo aptitude install libgeos-dev python-lxml libgdal-dev python-shapely

Note

Check that the python-shapely package is >=1.2, if it is not you need to install it with pip install Shapely.

Dependency details

libproj

MapProxy uses the Proj4 C Library for all coordinate transformation tasks. It is included in most distributions as libproj0.

PIL

The Python Image Library (PIL) is used for the image processing and it is included in most distributions as python-imaging.

The development version of PIL contains some enhancements for PNGs. You can install this version from source with:

sudo aptitude install build-essential python-dev libjpeg-dev \
  zlib1g-dev libfreetype6-dev
pip install https://bitbucket.org/olt/pil-2009-raclette/get/default.tar.gz

YAML

MapProxy uses YAML for the configuration parsing. It is available as python-yaml, but you can also install it as a Python package with pip install PyYAML.

Shapely and GEOS (optional)

You will need Shapely to use the coverage feature of MapProxy. Shapely offers Python bindings for the GEOS library. You need Shapely (python-shapely) and GEOS (libgeos-dev). You can install Shapely as a Python package with pip install Shapely if you system does not provide a recent (>= 1.2.0) version of Shapely.

GDAL (optional)

The coverage feature allows you to read geometries from OGR datasources (Shapefiles, PostGIS, etc.). This package is optional and only required for OGR datasource support. OGR is part of GDAL (libgdal-dev).

lxml (optional)

lxml is used for more advanced WMS FeatureInformation operations like XSL transformation or the concatenation of multiple XML/HTML documents. It is available as python-lxml.

Install MapProxy

Your virtual environment should already contain pip, a tool to install Python packages. If not, easy_install pip is enough to get it.

To install you need to call:

pip install MapProxy

You specify the release version of MapProxy. E.g.:

pip install MapProxy==1.1.0

or to get the latest 1.1.0 version:

pip install "MapProxy>=1.1.0,<=1.1.99"

To check if the MapProxy was successfully installed, you can call the mapproxy-util command.

mapproxy-util --version

Create a configuration

To create a new set of configuration files for MapProxy call:

mapproxy-util create -t base-config mymapproxy

This will create a mymapproxy directory with an example mapproxy.yaml and seed.yaml configuration.

Refer to the configuration documentation for more information. With the default configuration the cached data will be placed in the cache_data subdirectory.

Start the test server

To start a test server:

cd mymapproxy
mapproxy-util serve-develop mapproxy.yaml

There is already a test layer configured that obtains data from the Omniscale OpenStreetMap WMS. Feel free to use this service for testing.

MapProxy comes with a demo service that lists all configured WMS and TMS layers. You can access that service at http://localhost:8080/demo/