"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

GeoServer Development Setup



Mailing lists

Git resources



  1. Obtain a Git client
    • SourceTree is recommended for Windows; it comes with a command-line interface
    • Linux has git for command-line and gitk for graphical history display
  2. Configure your identity
    git config --global user.name "Your Real Name"
    git config --global user.email Your.Real.Name@example.org
  3. Configure your line ending settings
    • Windows
      git config --global core.autocrlf true
      git config --global core.safecrlf true
    • Linux/Mac
      git config --global core.autocrlf input
      git config --global core.safecrlf true
  4. (Optional) Make a GitHub account

Java 7 JDK

  • Obtain a Java 7 JDK
    • Oracle JDK 7 is easier for Windows, download from Oracle
    • OpenJDK 7 is easier for Linux as distribution packages work well; for Debian/Ubuntu:
      apt-get install openjdk-7-jdk
    • OpenJDK has no fonts and WMS unit test have required tweaking for robustness to support OpenJDK

Apache Maven 3

  • Obtain Apache Maven 3
    • Avoid Linux distribution packages as these have been notoriously broken in the past (yes, Ubuntu, we mean you)
  • A script or batch file on your path may ease command line use and avoid contaminating your global environment
    • On Windows a batch file (mvn.bat):
      @echo off
      set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_your_jdk_build_number_goes_here
      set M2_HOME=C:\Program Files\maven3
      set MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128m"
      set PATH=%JAVA_HOME%\bin;%M2_HOME%\bin;%PATH%
      mvn -llr %*
    • On Linux (mvn):
      export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
      export M2_HOME=/path/to/your//maven3
      export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128m"
      export PATH=$JAVA_HOME/bin:$M2_HOME/bin:$PATH
      exec mvn -llr "$@"
  • Adjust for your memory/performance requirements

Command line

  • Obtain a shell or command prompt
  • Check that your correct Maven and JDK versions are shown with:
    mvn -version


  • Obtain Eclipse JEE
    • JEE strongly recommended as it contains server debugging support and XML editors
  • Eclipse Luna works


  • Clone these Git repositories:
    git clone -o geotools https://github.com/geotools/geotools
    git clone -o geowebcache https://github.com/GeoWebCache/geowebcache
    git clone -o geoserver https://github.com/geoserver/geoserver
  • You can later fork these on GitHub and add your forks as new remotes:
    git remote add yourgithubusername git@github.com:yourgithubusername/repositoryname.git


Build these projects sequentially, in this order.


  • Change into geotools directory and run:
    mvn -B -nsu -Djava.awt.headless=true -Dtest.maxHeapSize=256m -Dtest.maxPermSize=128m -DdownloadSources=true -Dall clean install eclipse:clean eclipse:eclipse


  • Change into geowebcache/geowebcache directory and run:
    mvn -B -nsu -Djava.awt.headless=true -Dtest.maxHeapSize=256m -Dtest.maxPermSize=128m -DdownloadSources=true clean install eclipse:clean eclipse:eclipse


  • Change into geoserver/src directory and run:
    mvn -B -nsu -Djava.awt.headless=true -Dtest.maxHeapSize=256m -Dtest.maxPermSize=128m -DdownloadSources=true -DconfigDirectory=../../../data -PallExtensions -Papp-schema -Prelease clean install eclipse:clean eclipse:eclipse


  • -llr (in the script at the top) stops Maven from remembering from where it downloaded an artifact; this turns off a poorly thought-out feature of Maven
  • -B specified batch mode and prevents log-filling download progress information
  • -nsu stops Maven from downloading unwanted remote SNAPSHOTs that were built after your local build and also makes builds faster as SNAPSHOT require a remote resource check
  • -Djava.awt.headless=true ensures all interactivity is disabled
  • -Dtest.maxHeapSize=256m not strictly necessary unless unit tests fail by running out of heap in which case increase this limit
  • -Dtest.maxPermSize=128m not strictly necessary unless unit tests fail by running out of permgen in which case increase this limit
  • -DdownloadSources=true download source jars to make Eclipse debugging much, much better
  • -Dall build all GeoTools modules
  • -DconfigDirectory../../../data= combined with -Prelease ensures that the release demo data is available when debugging GeoServer in Eclipse
  • -PallExtension build all GeoServer extensions
  • -Papp-schema add app-schema to the GeoServer gs-web-app module path so the app-schema module is available in Eclipse
  • -Prelease build all modules required for a GeoServer release (required before running mvn assembly:attached to build release bundles) and use the release data in Eclipse
  • More information on the Jenkins page:



  • Import the GeoTools formatter settings into Eclipse in Preferences / Java / Code Style / Formatter from the GeoTools working directory: build/eclipse/formatter.xml
  • These settings use four-space indenting and never tabs; they are otherwise very close to the Sun Java Code Conventions.


  • Change your XML Editor preferences to use four-space indenting and never tabs.

Old sections yet be be refactored

Use Maven to build and configure Eclipse projects

Maven is used to retrieve the >140 jar dependencies and store them in a local repository. This will take some time. Maven must be run in a directory with a pom.xml file (for GeoServer this is a subdirectory).

Change into each of the directories and use the command for a full rebuild:
  • In geotools
    • mvn -Dtest.maxHeapSize=768m -DdownloadSources=true -Dall -Pwebservice clean install eclipse:clean eclipse:eclipse
  • In geoserver/src
    • mvn -Dtest.maxHeapSize=768m -DdownloadSources=true -PallExtensions -Poracle -Papp-schema -Pwebservice clean install eclipse:clean eclipse:eclipse
  • Maven goals are executed for each module in the order given. Eclipse goals are last to leave workspace alone if tests fail.
  • -Dtest.maxHeapSize=256m restricts unit test JVM heap size to 256m, for consistency with OpenGeo and Computational Geoscience continuous integration. Use this if you want your builds to behave the same way, so you are not surprised by an unexpected build failure when the build succeeds on your desktop. This option will also make unit tests fail on 64-bit JVMs. frown
  • -Dtest.maxHeapSize=1024m may be required to get some tests to pass under a 64-bit JVM. This might no longer be the case since Gabriel and Rini put app-schema on a diet. :-P
  • -Dall for GeoTools ensures all optional modules are built. This allows you to detect when any changes you make break an optional supported module. It also gives you access to the new generation of JDBC DataStores. You will need this later when you include Oracle support for GeoServer.
  • -Pwebservice in GeoTools enables the unsupported webservice module. This option can be left out by those who just want to use app-schema, but core app-schema developers should use this module to ensure they do not break the webservice module. (Our buildbot uses this option). The same option in GeoServer is used to build the community/app-schema/webservice-test module, which is the corresponding unit tests for the GeoTools webservice module.
  • -PallExtensions for GeoServer ensures all optional extensions are built. This allows you to detect when any changes you make break an optional supported extension.
  • -Poracle for GeoServer includes Oracle support in the web application.
  • -Papp-schema ensures app-schema support is included in Eclipse dependencies for the GeoServer web-app module for debugging, and in the GeoServer deployment bundle.
  • -Psqlserver is required in GeoServer if you need Microsoft SQL Server support. See details at GeoserverMsSqlServerConnectivity.
  • -DdownloadSources=true is always optional. This downloads sources for dependencies, where available. Maven attaches source in Eclipse projects, allowing source browsing into dependencies. This is very useful for debugging in Eclipse. One downside is it will make Maven slower because it will check for updated source for every dependency, for every module. You may wish to use it only now and then.
  • If no pom files or dependencies have changed, you can omit the eclipse goals.
  • -Dorg.geotools.image.test.enabled=true may be specified if you want to perform optional perceptual diff tests for app-schema WMS support. These will only actually be performed if perceptual diff is in fact installed on your computer. This option is particularly recommended if you are (possibly) modifying the app-schema wms functionality.
  • -o can be added to run offline. This will make the build faster by not checking for updated remote artifacts. You can use this flag if you are rerunning a build shortly after running an online build.
  • -DskipTests=true can be added to skip tests, making the build process much, much faster. Tests are there to help you detect problems, so avoid skipping them. Never commit anything to the subversion repository without running all tests, or you risk breaking the build. Skipping tests will also cause test artifacts to not be built, and break dependencies on test artifacts.
  • -Papp-schema-online-test enable online testing profile. Please read AppSchemaTestDatabase to prepare your databases for the app-schema online tests suite. More information can be found http://docs.geoserver.org/latest/en/developer/programming-guide/app-schema/index.html

GeoServer WAR built with application schema support

The Maven build process described above creates a GeoServer WAR file:
  • src/web/app/target/geoserver.war
This WAR file is ready for deployment in a servlet context. It has a minimal (i.e. empty) configuration.

Add Maven repository to Eclipse build path

Eclipse needs to find the Maven-downloaded jars for compilation. Under Preferences > Java > Build Path > Classpath Variables I added an entry called M2_REPO set to .m2\repository directory in my home directory (this is my local Maven repository).

Eclipse workspaces

I created separate Eclipse workspaces for GeoServer and GeoTools called geoserver and geotools respectively.

When working with external tools it can be easier to have Eclipse automatically refresh its state to reflect filesystem changes.
  • You can go to Preferences > General > Workspace and select Refresh automatically.
  • To prevent Eclipse from fighting with Maven, shut down Eclipse during a Maven compile or Maven install, otherwise Maven pre-build clean will trigger a concurrent Eclipse build.
  • During unit tests Subclipse will go insane trying to get revision history as the test modifies the filesystem. This annoyed me enough to turn off auto-refresh.
If you leave auto-refresh turned off, you need to select all projects and press F5 to get Eclipse to recognise changes.

Working Set

A working set is a group of elements shown in the different Eclipse views. Working sets are used to clearly separating projects. This can become a very useful feature when you are working simultaneously in many non-directly related projects. Organising your different project groups in working sets will speed up the process of finding the desired elements and will decrease the view visual clutter.

To define a working set, click the Package Explorer menu icon (the inverted triangle) and select Configure Working Set. Here you will be able to create a new working set and to select its related resources, as well as to edit or remove existing working sets. Every available working set will be shown the next time you click on the view triangular icon.

To configure GeoServer and GeoTools to use a single workspace (Optional), select a workspace (or create a new one) and create working sets for both GeoServer and GeoTools respectively. Under Workspace content, select and add the desired packages. Click Finish to confirm the changes.

Notes: All packages from every project added will be listed and a good way to determine which packages are required would be to load the project in an new instance of Eclipse. Under Navigator view, take note of all the packages included and add them accordingly.

To "load" the working sets, navigate to Configure Working Set once again, and select checkbox(es) to load the desired working set(s).

Set Java 7 as default JRE for Eclipse workspace

Under Window > Preferences > Java > Installed JREs I added Java\jdk1.6.0_whatever (browsing under Program Files) and made it the default for the workspace.

I set the default VM arguments to: -Xmx512m -ea . I found this to be sufficient heap for my purposes. The -ea enables any assertions that might be present.

It should be fine to use the JRE instead of the JDK. One disadvantage of the JRE is that it does not come with source for the runtime, but it is easy to attach source from the JDK. In Eclipse:
  • Press Ctrl-Shift-T and open type Math from java.lang
  • If you do not see the source, press button to attach source, and select the the src.zip in the JDK root directory (for the JDK corresponding to the JRE).
  • You might need to close Math and restart Eclipse before it recognises the source attachment.
If you use the JDK, Eclipse will find the source automagically, so you will not need the above workaround.

Set Java compiler compliance for Eclipse workspaces

  • Maven should set compliance for each Eclipse project it creates, so this step should not be necessary. I use it to be robust against misconfigured modules and to make any extra projects I add consistent.
  • Compiler compliance level is set under Preferences > Java > Compiler.
  • Set compliance level to 1.6.

Set code formatter to use GeoTools conventions

Use the GeoTools code conventions for both GeoTools and GeoServer. The GeoTools formatter profile for Eclipse is stored in your geotools-trunk checkout:
  • build/eclipse/formatter.xml
Import this profile into each workspace using Preferences > Java > Code Style > Formatter.

For GeoTools, you can also set the Code Templates, which include automatic generation of the copyright header in new files.
  • build/eclipse/codetemplates.xml
See also the GeoTools style guide (Oracle Java, spaces not tabs, width 100):

Configure Eclipse XML formatting

Make your Eclipse XML formatting style consistent with the GeoTools / GeoServer Java coding style: 100 character line width with four-space indenting. This is not an official GeoTools / GeoServer rule, but app-schema developers use a lot of XML and we care. smile

In your Eclipse XML Editor settings (XML > XML Files > Editor) set:
  • Line Width: 100
  • Indent using spaces
  • Indentation size: 4

Import projects into Eclipse

This step makes Eclipse recognise the project metadata generated by Maven. Use File > Import > General > Existing Projects into Workspace:
  • Import all projects from geoserver-trunk into the geoserver-trunk workspace.
  • Import all projects from geotools-trunk into the geotools-trunk workspace.
  • After importing, you might need to restart Eclipse to ensure directories are fully refreshed (e.g. by Subclipse). Your mileage may vary.
All projects should now compile in Eclipse. To test this:
  • Use Project > Clean > Clean All Projects to delete all class files.
  • I have Eclipse configured Preferences > General > Workspace with Build Automatically selected (this is the default), so it then recompiles everything.

GeoServer configurations

GeoServer configurations can be exported or checked out from Subversion to external directories and referenced with the -DGEOSERVER_DATA_DIR=/whatever Java VM argument.

Debugging GeoServer using embedded Jetty

  • The embedded Jetty application main class is org.geoserver.web.Start in the GeoServer web-app module (in src/test/java).
  • Use the Debug dialog to make Java Application launch configurations for this class.
  • In each Java Application launch configuration, add a VM argument -DGEOSERVER_DATA_DIR=/wherever pointing to the location of a GeoServer configuration.
  • If you want to access an Oracle Spatial database, you need add an Oracle JDBC driver (e.g. ojdbc5.jar) to your classpath.
    • The driver can be obtained from either of:
    • Copy the Oracle JDBC driver to a local directory or Eclipse project in your workspace.
    • Add ojdbc5.jar on the Classpath tab of your Eclipse launch configuration.
  • If you want to access a Microsoft SQL Server database, you need add a SQLJDBC driver (e.g. sqljdbc.jar) to your classpath.
  • Debug with this launch configuration.
  • You can make WFS requests in a web browser with URLs like this:
Configurations can be set in eclipse using its vm arguments:
  • -DGEOSERVER_DATA_DIR=C:\VWork\test\data
  • -Dapp-schema.properties=C:\VWork\test\app-schema.properties
  • -Djetty.config.file=C:\VWork\test\earthresource.jetty.xml
Topic revision: r52 - 28 Oct 2014, BenCaradocDavies

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).