README

# CGImap

[![CI](https://github.com/zerebubuth/openstreetmap-cgimap/actions/workflows/docker_bookworm.yml/badge.svg)](https://github.com/zerebubuth/openstreetmap-cgimap/actions/workflows/main.yml) [![CodeQL](https://github.com/zerebubuth/openstreetmap-cgimap/actions/workflows/codeql.yml/badge.svg)](https://github.com/zerebubuth/openstreetmap-cgimap/actions/workflows/codeql.yml)

## Overview

CGImap is a C++ implementation of performance critical parts of the OpenStreetMap API as an FastCGI process.

As CGImap doesn't manage any database schemas and tables on its own, it can only be deployed alongside the openstreetmap-website application to replace selected API endpoints by their performance optimized counterparts. CGImap directly interacts with the APIDB, and completely bypasses the openstreetmap-website Rails application. See the [CGImap wiki page](https://wiki.openstreetmap.org/wiki/CGImap) for further details.

CGImap implements the following 25 [OSM API 0.6](https://wiki.openstreetmap.org/wiki/API_v0.6) endpoints:

* the "map" API call,
* single node, way and relation fetches,
* multiple node, way and relation fetches,
* the "full" way and relation calls and
* changset metadata downloads, including discussions,
* single node, way and relation history calls,
* single node, way and relation specific version fetches,
* multiple node, way and relation specific version fetches,
* relations for element (node, way, relation),
* ways for node,
* create changeset,
* update changeset,
* close changeset,
* changeset downloads,
* changeset uploads.

## Requirements

CGImap uses a PostgreSQL server for the APIDB backend.

If you're running a Debian or Ubuntu system these can be installed
using the following command:

    sudo apt-get install libxml2-dev libpqxx-dev libfcgi-dev zlib1g-dev libbrotli-dev \
      libboost-program-options-dev libfmt-dev libmemcached-dev libcrypto++-dev libyajl-dev

Note that C++20 is _required_ to build CGImap.

The build system used is cmake.

Note that the full set of packages needed from a fresh install (tested
with Ubuntu 22.04, Debian 12 and 13) - you may already have many or all of these - is:

    sudo apt-get install git build-essential cmake make

Note: On Ubuntu 24.04, the distribution-provided libpqxx-dev package has some issues
with C++20. Users should build and install their own 7.10.0 version of the library
for the time being. Refer to `docker/ubuntu/Dockerfile2404` for more details.

To build the system from scratch, first check out the source code (skip
this step if you've already got the source):

    git clone https://github.com/zerebubuth/openstreetmap-cgimap.git

Then change to the source code directory to configure and build using cmake:

    cd openstreetmap-cgimap/
    mkdir build
    cd build
    cmake ..
    cmake --build .

You should now have a "./openstreetmap-cgimap" executable in the current
directory. For system-wide installation you still need to run:

    sudo make install

For historic reasons, CGImap provides a number of shared libraries which were
originally intended for reuse by other applications. As there are no real world
consumers of these libraries, a static build is used by default. If you want
to build with dynamic libraries instead, you can use the following cmake parameters:

    cmake .. -DBUILD_SHARED_LIBS=ON

## Setup

To run CGImap binary, use the command:

    ./openstreetmap-cgimap --dbname=openstreetmap --username=user --password=pass \
         --dbport=5432 --socket=:54321 --logfile=/tmp/logfile \
         --daemon --instances=10

Instead of a world-accessible TCP socket 54321, you might want to use 127.0.0.1:54321
to restrict access to the current host, or use plain filename like "--socket mysocket"
for a Unix domain socket instead.

CGImap has to be used with a FastCGI enabled HTTP server like lighttpd, apache2 etc. See the instructions below to use CGImap with lighttpd or apache2.

A sample lighttd.conf file is provided, which can be used for testing purposes only. To test CGImap with lighttpd you will need to install lighttpd:

	sudo apt-get install lighttpd

Edit the supplied lighttpd.config file to include your CGImap path and run it with the lighttpd like

	/usr/sbin/lighttpd -f lighttpd.conf

You can then access the running instance at `http://localhost:31337/api/0.6/map?bbox=...`

The api.osm.org instance runs CGImap as a daemon and Apache with
[mod_proxy_fcgi](https://httpd.apache.org/docs/trunk/mod/mod_proxy_fcgi.html).

### Specifying configuration options

Typically you will need to modify the database connection parameters and path
to the executable. See `./openstreetmap-cgimap --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 variable `CGIMAP_DBNAME`.

Besides environment variables and command line options, CGImap configuration settings can also be provided in an INI-style config file. Use command line parameter `--configfile` to define the file location.

Example:

```ini
dbname=openstreetmap
host=localhost
username=user
password=pass

#update-host=127.0.0.1
#update-dbname=openstreetmap
#ratelimit=100000

# Expert settings (should be left to their default values in most cases)
# see --help for further details
#
#map-area=10
#disable-api-write=
#max-payload=50000000

```

### Automatic startup as Daemon Service

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 `/etc/init.d/cgibin` and
change the mode to 755, and owner:group to root:root.

For more recent operating systems using systemd instead of init
`scripts/cgimap.service` is provided to run CGImap as a daemon.  To
use it modify the paths, set environment variables or the settings
in the config file, copy it to `/etc/systemd/system/cgimap.service`.
Change the mode to 755, and owner:group to root:root.  To enable the service use
`systemctl enable cgimap` and to start the service `systemctl start cgimap`.

An example of this can be found in
[OSM Chef](http://git.openstreetmap.org/chef.git/blob/HEAD:/cookbooks/web/recipes/cgimap.rb).

### Configuring Apache as FastCGI proxy

Fcgi programs can be deployed with Apache using `mod_fastcgi_handler`,
`mod_fcgid`, `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/cgimap.conf`. To use this on a Ubuntu-based
system you need to copy the configuration 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.

## Docker

This repository includes a `Dockerfile`, which can be used to build a cgimap image based on Ubuntu 24.04:

    docker build -f docker/ubuntu/Dockerfile2404 . -t cgimap

Due to the multi-stage build process, Docker version 17.05 or higher is required. The resulting cgimap image has a total size of about 140MB. `openstreetmap-cgimap` is built as a static binary.

https://github.com/zerebubuth/openstreetmap-cgimap/pull/213 has additional configuration details on how to use the cgimap image in a complete development environment, which includes the Rails port, a Postgresql DB, lighttpd as reverse proxy, and openstreetmap-cgimap.


## Database Permissions

The read only apidb backend requires permissions to SELECT on the Postgres server.
Update database connections require additional permissions to INSERT/UPDATE/DELETE
data, as well as creating temporary tables.

It is recommended that a separate unix account is used for
CGImap to avoid any possibility of data corruption.

## Testing

To run the test suite you will need additional packages installed:

    sudo apt-get install postgresql-all postgresql-common postgresql-server-dev-all

Tests can be built by using the Debug build type or explicitly setting the BUILD_TESTING: option

    cmake .. -DCMAKE_BUILD_TYPE=Debug

or

    cmake .. -DBUILD_TESTING=ON

The test suite can then be run using `cmake --build . -t test` / `ctest` as normal.

Test cases are executed under `pg_virtualenv`, i.e. no further steps are needed to create databases as your user.

<!--
## Formatting

The CGImap code is formatted using
[clang-format](http://clang.llvm.org/docs/ClangFormat.html) in a style
which is based on the "LLVM style" which ships with
`clang-format`.
<!--
To enable an automatic reformatting option, provide the `--with-clang-format`
option to `configure` and then reformatting can be done across the
whole set of source files by running:

    make clang-format

Ideally, this should be done before committing each set of changes.
-->

## Acknowledgements

CGImap contains code from and is partly based on the following:

* [modosmapi](http://code.google.com/p/modosmapi/) by
  d40cht and japplebyalis.
* [quad_tile.c](https://github.com/openstreetmap/openstreetmap-website/blob/master/db/functions/quadtile.c)
  by TomH.
* [GNU CGICC](http://www.gnu.org/software/cgicc/)
  by Stephen F. Booth and Sebastien Diaz.
* [libxml++](https://gitlab.gnome.org/GNOME/libxmlplusplus/)
  by The libxml++ development team
* [Catch2](https://github.com/catchorg/Catch2)
  by Catch2 Authors
* [SJParser](https://gitlab.com/dhurum/sjparser) by Denis Tikhomirov