on Software

Your Own OSM WMS

04 Mar 2015

Open Street Map is many things, and also a beautiful example of the prosperous nature of community projects. So why not make available what is good to more people, such as our customers.

I would like to show how to publicise OSM data via a corporate WMS. For the example I will use OSM Data for Ireland, simply because the download is small. The full range of available data is available on the Planet.osm page in the OSM Wiki.


So lets start with downloading the data itself. The download is about 90MB. We’ll open up a fresh directory for that:

$ cd ; mkdir -p osm/data ; cd osm/data
$ curl -O



The data is here, we cannot use that as is it though. The file at hand is in Protocolbuffer Binary Format and must be converted to something I can serve through GeoServer via WMS. Among the options Shapefile is the quickest-to-setup choice. So lets go for that. I am running a Debian system, so my day is shiny :-)

$ sudo apt-get -y install osmjs
$ osmjs -2 -m -l sparsetable \
    -j /usr/share/osmjs/shape_export.js \

Let me explain that: I first installed the osmjs tool through the debian package manager. The osmjs tool can read and convert PBF files. The tool’s package also contains sample ‘configurations’ - which really are Javascript files - for exporting to Shapefile, and I simply use one of them.

After a while there are three shapefiles in the current directory: landuse.shp, pois.shp, and roads.shp. This itself is already something that can be used in many GIS systems.

But I want WMS.


Lets download and setup Jetty.

$ cd ; cd osm
$ curl -L '' \
  | zcat | tar xf -
$ mkdir jetty-base ; cd jetty-base
$ java -jar ../jetty-dis*/start.jar --add-to-start=http,deploy

You now have a configured Jetty with a jetty.base separate from the installation. What I did there can be read in the documentation, in particular in Creating a new Jetty Base.

Jetty alone cannot do WMS, hence let’s go and put GeoServer into the game.


For our purposes I recommend downloading the “Web Archive”. It can be downloaded from They do not offer streamable packages for me to offer hacky commands. You need to extract geoserver.war into ~/osm/jetty-base/webapps.

Jetty can be started by running the following in your console:

$ mkdir geoserver-data
$ export GEOSERVER_DATA_DIR=geoserver-data
$ java -jar ../jetty-dis*/start.jar &

GeoServer needs a data directory, which we define to be ./geoserver-data. Our OSM Layers can now be configured in GeoServer.


To define WMS Layers in GeoServer from a directory of Shapefiles, open a browser and point to the url

the root account password is available in the data directory: cat geoserver-data/security/

This takes quite a number of clicks and I compress this as lot. Do not hesitate to read the Geoserver Documentation if you’re new to it.

  1. On the left side, in the “Data” group, click “Workspaces”, then “Add new Workspace” and enter a name and an URL: { % img /images/osm-a.png %}
  2. Then, on the left side, click “Stores” and “Add new Store” and the first choice “Directory of spatial files (shapefiles)” is the one you want. Give it a name like “osm-ie” and make the location point to the directory where you generated the shapefiles above, e.g. file:/home/acefael/osm/data.
  3. After creating the Store GeoServer automatically discovers the Shapefiles and offers to publish them, i.e. making WMS Layers from them: { % img /images/osm-b.png %}. Simply click on “Publish” in the “landuse” row to make a WMS layer.
  4. The upcoming dialog has myriads of options. Fundamentally you want to enter “EPSG:4326” into “Declared SRS” and compute the bounding box and the lat/lon bounding box from the data. Then Save.
  5. To see your work, select “Layer Preview” on the left to open up the following screen. { % img /images/osm-c.png %} Then click OpenLayers. Then marvel.

You can publish the other Shapefiles as layers by navigating to “Layers” in the navigation on the left side and then choosing “Add new Layer”.


This is a lot of ground and I recommend reading the documentation for Jetty, GeoServer and of course the Planet.osm page in the OSM Wiki.

Nonetheless I hope you benefit from this and have your own corporate WMS up and running soon. Oh and don’t forget to leave a comment if you like this.