CGImap is a C++ implementation of some parts of the OpenStreetMap API as an FCGI process. The rails implementation of the "map" call had a few problems with memory - it uses a lot of it and there is a leak which makes it annoying to use in long-running environments, like the main OSM server.
CGImap attempts to address these memory problems and makes it easier to optimise the queries, something which is also a bit of a pain to do in Rails.
Currently, CGImap implements:
- the "map" API call,
- single node, way and relation fetches,
- multiple node, way and relation fetches and
- the "full" way and relation calls.
CGImap depends on the following libraries. Versions used during development are in brackets. Other versions may work, but YMMV.
- libxml2 (2.9.1+dfsg1-3ubuntu4.4)
- libpqxx3 (3.1.1-0ubuntu4)
- libfcgi (2.4.0-8.1ubuntu5)
- libboost (1.54.0-4ubuntu3.1)
If you're running a Debian or Ubuntu system these can be installed using the following command:
sudo apt-get install libxml2-dev libpqxx3-dev libfcgi-dev \ libboost-dev libboost-regex-dev libboost-program-options-dev \ libboost-date-time-dev libboost-filesystem-dev \ libboost-system-dev libmemcached-dev
The build system used is GNU Make, using pkg-config to provide some of the flags.
Note that the full set of packages needed from a fresh install (tested with Ubuntu 14.04.1) - you may already have many or all of these - is:
sudo apt-get install git build-essential automake autoconf libtool
To build the system from scratch, first check out the source code (skip this step if you've already got the source):
git clone git://github.com/zerebubuth/openstreetmap-cgimap.git
Then change to the source code directory to configure and build:
cd openstreetmap-cgimap/ ./autogen.sh ./configure make
You should now have a "./map" executable in the current directory.
A sample lighttd.conf file is provided, which can be used to test. To test CGImap with lighttpd use the supplied config file with lighttpd and run cgimap on the command line with a command like
./map --port 54321 --backend apidb --dbname openstreetmap
You can then access the running instance at
The api.osm.org instance runs CGImap as a daemon and Apache with
An init.d script to run CGImap as a daemon is supplied in
scripts/cgimap.init. To use it modify the paths and environment
variables to suit your installation, copy it to
change the mode to 755, and owner:group to root:root.
An example of this can be found in OSM Chef.
Typically you will need to modify the database connection parameters and path
to the executable. See
./map --help for a list of options. To convert a
command line option to an environment variable append
CGIMAP_ to the option
and capatalize it. For example, the option
--dbname becomes the environment
Fcgi programs can be deployed with Apache using
mod_fastcgi, and on recent versions
mod_proxy_fcgi. A sample
Apache configuration file that will work in conjunction with CGImap as a
daemon is supplied in
scripts/cgibin.conf. To use this on a Ubuntu-based
system you need to copy the cofiguration to where Apache will read it and
create an api directory:
sudo cp scripts/cgimap.conf /etc/apache2/sites-available/cgimap sudo chmod 644 /etc/apache2/sites-available/cgimap sudo chown root:root /etc/apache2/sites-available/cgimap sudo mkdir /var/www/api sudo a2ensite cgimap sudo service apache2 restart
The apache modules mod_proxy and mod_fastcgi_handler must also be enabled.
The apidb backend requires permissions to SELECT and CREATE TEMPORARY on the
Postgres server. For situations where temporary tables cannot be created there
The pgsnapshot backend requires permissions to SELECT and CREATE TEMPORARY on the Postgres server, but will not work in situations where temporary tables cannot be created.
In both cases it is recommended that a separate account is created for CGImap to avoid any possibility of data corruption. Care has been taken programming CGImap but, as with most C++ applications, there is the chance of an exploitable flaw leading to complete pwnage.
To run the test suite using
make check you will need additional
sudo apt-get install postgresql postgresql-contrib postgis \ ruby libxml-ruby ruby-pg
And you will need to be able to create databases as your user:
sudo -u postgres createuser -s $USER
The CGImap code is formatted using
clang-format in a style
which is based on the "LLVM style" which ships with
clang-format. Note that version 3.6 or later is needed to avoid
introducing problems with formatting try-catch blocks. To enable an
automatic reformatting option, provide the
configure and then reformatting can be done across the
whole set of source files by running:
Ideally, this should be done before committing each set of changes.
CGImap contains code from and is partly based on the following: