Microcosm
Microcosm is a map database server implemented in PHP. The main goals are to implement API v0.6 on a platform that is easy and convenient, particularly with respect to hosting and installation. It can only handle small databases, unlike the Rails Port. All the API calls are supported, but many features are still lacking. The back end database uses SQLite, but the software is designed to be extensible to other back ends. Microcosm is compatible with JOSM and Merkaartor, but not tested using Potlatch.
Sqlite must be compiled with R*Tree enabled, but this seems to be the default for some linux distributions (e.g. Debian and Ubuntu). Notably, CentOS is NOT compiled with R*Tree enabled. CentOS is widely used in shared hosting and makes running Microcosm problematic in these circumstances.
The license is simplified BSD. Send comments and suggestions to TimSC.
Contents |
Issues with Running Independent Servers
- Because the object IDs are independent of the main OSM database, there is the potential for ID number collision. This makes merging data a challenge. Make sure you know what you are doing before running an independent map server.
- Understand the legal implications of what you are doing. Data supplied under one license cannot always be uploaded to another server using a different license.
Installation
- Install a web server (e.g. apache), PHP and the Sqlite PHP module. On Debian/Ubuntu:
sudo apt-get install libapache2-mod-php5 php5-sqlite
- Download [1] and extract files on web server
- Use a browser to access AddUser.php in the "web" folder, on the web server. Add new user accounts as required.
- Check config.php for other settings
- Import starting map data using import.php, which may only be run from the command line (this can be done before upload, if that is easier). Use something similar to:
php import.php map.osm
- Set the initial values for new changesets, nodes, ways and relations in nextchangesetid.txt, nextnodeid.txt, nextrelationid.txt, nextwayid.txt.
- Set permissions of everything to all writeable.
- Configure your editor to use the custom API URL. Specifically the URL should be the location of microcosm.php
Configuring Default /api/0.6 Url using mod_rewrite
The simple installation of microcosm has a URL ending in "php". Sometimes it is preferable to have the more conventional /api/0.6 URL for the API. This may be achieved on apache using mod_rewrite. This enables requests to the /api/0.6 to be redirected to the PHP script.
- Install microcosm on an apache web server as stated above
- Enable overrides in apache configuration for this site. This is sometimes in this configuration file "/etc/apache2/sites-available/default". Within the <Directory /var/www/> tag, set "AllowOverride All".
- Copy and rename "example-.htaccess" to ".htaccess" in the website root folder. Open it and check the settings are ok.
- Enable mod_rewrite and restart apache
sudo a2enmod rewrite sudo apachectl restart
- The INSTALL_FOLDER_DEPTH parameter in config.php might need adjustment.
nginx config
location /api/ {
fastcgi_pass unix:/var/spool/php-fpm.socket; # PHP-FPM socket
root /home/web/htdocs/m/; # Microcosm directory
fastcgi_index microcosm.php;
include fastcgi_params;
fastcgi_split_path_info ^(\/api)(.*)$;
fastcgi_param SCRIPT_FILENAME $document_root/microcosm.php;
fastcgi_param PATH_INFO $fastcgi_path_info;
}
lighttpd config
url.rewrite = ( "^/api/(.*)$" => "m/microcosm.php/$1" )
Enable PHP Debug Messages
To trouble shoot PHP scripts, it is often helpful to have errors turned on. Edit your php.ini (for me it is /etc/php5/apache2filter/php.ini) and set:
display_errors = On
and restart apache:
sudo apachectl restart
Upgrading Versions
Because there is no system of schema updates, the database should be exported, then a clean install used to import the data.
