This tutorial is designed for intermediate level users of GeoServer as it explains how to properly configure your GeoServer installation to run outside of localhost:8080 using an Apache ProxyPass.  This tutorial will also explain how to configure your web server to request data from a remote host by setting up your own proxy.cgi.  This can help solve a common issue of trying to load data via WFS from a remotely hosted server, when using OpenLayers with GeoServer WFS.

I strongly recommend using a web browser that has access to developer tools which allow for greater debugging ability, ie Google Chrome or Mozilla Firefox (with the latest Firebug extension installed).  By completing this tutorial users will also learn how to change the default GeoServer login and password information.

Setting up the Apache ProxyPass for GeoServer Public Data Access

By default, GeoServer installs itself to run through localhost:8080, which is evident by the location of the GeoServer Web Admin Interface which can be found at http://localhost:8080/geoserver/web.  This configuration is great for rendering GIS graphical information on your own server using your own data.  However it does not allow you to publish your layers to public areas, ie. http://yourdomain.com/geoserver/web.  In order to setup the Apache ProxyPass we will have to modify the httpd.conf configuration file on your server, add in the ProxyPass information and restart your Apache Web Server for the settings to take effect.  On Linux systems enter the following commands:

su –
vi /etc/httpd/conf/httpd.conf

Use the arrow keys to scroll down to the <VirtualHost *:80> section used for yourdomain.com, press ‘I’ to enter INSERT mode, copy the text below and right click to paste the ProxyPass into your httpd.conf file right above the </VirtualHost> tag.

ProxyRequests Off
ProxyPreserveHost On
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPass /geoserver http://localhost:8080/geoserver
ProxyPassReverse /geoserver http://localhost:8080/geoserver

Press the ‘Esc’ key to exit INSERT mode, then save and close the file by entering :wq.

Now you must restart your Apache Web Server for the settings to take effect.

service httpd restart

To test the Apache ProxyPass try navigating to http://yourdomain.com/geoserver/web and see if the GeoServer Admin Web Interface appears.  Now requests sent to the public web address will be passed through the Apache ProxyPass to your GeoServer installation.

Changing the Default GeoServer Admin Login and Password Information

Now that your GeoServer is accessible to the outside world via http://yourdomain.com/geoserver/web, it is essential to modify the default administrator login of user ‘admin’ and password ‘geoserver’.  This information is stored within a file called users.properties which can be found in the GeoServer security directory, ex. /usr/local/geoserver/data_dir/security/users.properties.  To modify the login information enter the following commands on Linux:

vi /usr/local/geoserver/data_dir/security/users.properties

Again use the arrow keys to navigate to the line that says

admin=geoserver,ROLE_ADMINISTRATOR

Press ‘I’ to enter INSERT mode and change the username and password, when finished press ‘Esc’ and enter :wq to save and close.  Now try logging in using the new information you just setup.

Configuring an OpenLayers proxy.cgi for Loading Local and Remotely Hosted GeoServer WFS Data

A common problem when starting off using GeoServer and OpenLayers occurs when you try and host WFS data from your own GeoServer in an online public application.  If you are running a script stored on yourdomain.com and your OpenLayers code is trying to load a GeoServer WFS layer stored on your localhost you may run into the following error message.

XMLHttpRequest cannot load http://www.yourdomain.com/geoserver/wfs. Origin http://localhost is not allowed by Access-Control-Allow-Origin.

This error is caused by a security feature in XMLHttpRequest which was designed to request only from the domain it was loaded.  Because the request is coming from the online space, and trying to access the localhost it determines that the origins do not match.  A work around for this is to create a proxy.cgi script, and save it in the cgi-bin directory of your Apache Web Server, /var/www/cgi-bin/proxy.cgi.  Make sure to save your proxy.cgi to have executable permissions. An example OpenLayers proxy.cgi can be downloaded from here. http://trac.osgeo.org/openlayers/browser/trunk/openlayers/examples/proxy.cgi

Modify the file using the vi technique described above, adding into the allowedHosts variable ‘localhost’ and ‘localhost:8080’.  Save and close the file, :wq and restart the Apache Web Server for the settings to take effect

service httpd restart

To test if you have properly setup the OpenLayers proxy.cgi, navigate to http://yourdomain.com/cgi-bin/proxy.cgi.  If all goes well you should see the OpenLayers site.

To use this proxy.cgi within your OpenLayers application, you must include the following line.

OpenLayers.ProxyHost = "/cgi-bin/proxy.cgi?url=";

Now OpenLayers XMLHttpRequests are allowed to load information hosted on localhost or localhost:8080.  Now that the OpenLayers proxy.cgi has been setup, to allow further access to remotely hosted GeoServer WFS data simply add in all the remote host names you would like your application to access, then restart your Apache Web Server.

Users should now have a thorough understanding of how to configure their GeoServer installation for public and remote data access.  Users should also have the ability to modify the default GeoServer login information for greater security.  Users should also have gained the understanding of allowing public display of layers stored within their local GeoServer installation.