Getting Started with GeoServer

(For more resources related to this topic, see here.)

Installing Java

GeoServer is a Java application. So, we need to ensure that you have it installed and properly working on your machine, but you don't need to know how to write Java™ to install or to get started using GeoServer.

There are two main packages of Java. Depending on what you are planning to do with Java, you may want to install a JDK (Java Development Kit) or JRE (Java Runtime Environment). The former enables you to compile Java™ code, while the latter has all you need to run most Java applications.

Starting from release 2.0, GeoServer does not need a full JDK installation and you can go safely with JRE. It works well with Java 6 but as Java 7 is not deeply tested by developers, it should work but you may experience minor issues. Unless you have some strong reasons to use Java 7, you should use JRE 6.

In the 90s, Java development was started by Sun Microsystems. Sun has developed each new release until it merged into Oracle Corporation. While Oracle did not change the Java license to a commercial one, there are some license issues (maybe it would be worthy to add some reference here) preventing Oracle Java™ from being available on an Ubuntu repository.

On Ubuntu current releases, you will find OpenJDK already installed in the desktop edition; in the server, you need to choose it at setup. While there are a few users running GeoServer on OpenJDK with no issues, the developers community does not test it intensively and hence you can expect some performance loss.

Oracle Java™ should be your first choice unless you have some specific issues. In the following steps, we will use Oracle Java™ JRE. If your installation machine is a new one, then chances are that there is no Java runtime pre-installed. Let's check.

Time for action — checking the presence of Java on Windows

We will verify the presence of a JRE/JDK installation on Windows, using the following steps:

  1. From the Start menu, select Control Panel.

  2. Then select Programs. If your system has a JRE/JDK installed, you should see an icon with the Java logo as shown in the following screenshot. It is a shortcut to the Java control panel.

  3. Open the Java control panel and select the Java tab. Here you will find settings for JRE. Press the Show Me button to visualize the installed release and the installation folder.

What just happened?

You checked for the presence of Java on your computer. In case you didn't find it, we are going to install it in the next section. (If you did find it, skip to the Installing Apache Tomcat section.)

Time for action — checking the presence of Java on Ubuntu

We will check JRE/JDK installation from the command line.

  1. Log in to your server and run this command:

    ~ $ sudo update-alternatives --config java

  2. If there is no Java properly configured you should see an output like the following:

    update-alternatives: error: no alternatives for java.

  3. In case there is one or more Java installed the output will be similar to:

    There is only one alternative in link group java: /usr/lib/jvm/ java-7-openjdk-amd64/jre/bin/java Nothing to configure.


    There are 2 choices for the alternative java (providing /usr/bin/ java). Selection Path Priority Status ———————————————————— * 0 /usr/lib/jvm/java-6-openjdk/jre/bin/java 1061 auto mode 1 /usr/lib/jvm/java-6-openjdk/jre/bin/java 1061 manual mode 2 /usr/lib/jvm/java-6-sun/jre/bin/java 63 manual mode Press enter to keep the current choice[*], or type selection number:

What just happened?

requirement for our installation. We had the opportunity to check if the installed release, in case we found it, is suitable for running GeoServer.

Now we will go through the installation of JRE.

Time for action — installing JRE on Windows

We will install Oracle JRE 1.6. We are assuming that you didn't find any previous Java installation.

  1. Navigate to the Downloads tab at

  2. Select the installer for Windows 64-bit, that is, jre-6u37-windows-x64.exe, and save it in a convenient folder.

  3. Select the downloaded file and run it as an administrator; press the Yes button when asked from the User Account control.

  4. Go with the default settings and press the Install button.
  5. After it has been downloaded, you should see a window informing you about the success of installation.

What just happened?

We installed JRE on your Windows computer. The first requirement is now fulfilled and you can go over to the Tomcat installation.

Time for action — installing JRE on Ubuntu

We will install Oracle JRE 1.6. As mentioned previously, there is no Ubuntu package for Java 6; we are going to perform a manual installation.

  1. Visit the download area at

  2. Download the tar.gz archive, choosing the 32-bit or 64-bit archive, depending on the Ubuntu edition you are working with. You must accept the license agreement (reading it might be a nice idea) before you can select one of the tar.gz archives (be sure to avoid rpm archives as they are not for Debian-based Linux distribution).

  3. Save the archive to your home folder and extract it.

    ~ $ chmod a+x jre-6u37-linux-x64.bin ~ $ ./jre-6u37-linux-x64.bin

  4. The JRE 6 package is extracted into ./jre1.6.0_37 folder. Now move the JRE 6 directory to /opt and create a symbolic link to it in the default folder for libraries.

    ~ $ sudo mv ./jre1.6.0_37* /opt ~ $ sudo ln -s /opt/jre1.6.0_37 /usr/lib/jvm/

  5. Let's check the installation:

    ~ $ /opt/jre1.6.0_37/bin/java -version java version "1.6.0_37" Java(TM) SE Runtime Environment (build 1.6.0_37-b06) Java HotSpot(TM) Client VM (build 20.12-b01, mixed mode)

  6. Although not strictly requested by the GeoServer installation, it is worth configuring the JRE as the primary Java alternative in your system:

    ~$ sudo update-alternatives --install /usr/bin/java java /usr/lib/ jvm/jre1.6.0_37/bin/java 0

  7. Now you need to configure the Oracle JRE as default:

    ~ $ sudo update-alternatives --config java There are 2 choices for the alternative java (providing /usr/bin/ java). Selection Path Priority Status ------------------------------------------------------------ * 0 /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java 1061 auto mode 1 /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java 1061 manual mode 2 /usr/lib/jvm/jre1.6.0_37/bin/java 0 manual mode Press enter to keep the current choice[*], or type selection number: 2 update-alternatives: using /usr/lib/jvm/jre1.6.0_37/bin/java to provide /usr/bin/java (java) in manual mode.

  8. Clean your box by deleting the archive:

    ~$ rm jre-6u37-linux-x64.bin

What just happened?

We installed JRE. Now we can run a Java application on the JVM contained in the JRE. The JVM supports several different kinds of Java application; for example, a console-only application, an applet running in a browser, or a full desktop application. For GeoServer (a web application), we need another component on top of the JVM, that is, a servlet container.

Installing Apache Tomcat

Having correctly installed the JRE you can now pass on and install the servlet container. Servlet container, or web container, is the component server that interacts with the servlets. It is responsible for managing the lifecycle of servlets, mapping a URL to a particular servlet, and ensuring access security. It should implement Java servlet and JavaServer Pages technologies.

As for JRE, you have a few choices here; a brief list is at

Apache Tomcat, GlassFish, and JBoss are most popular and are all available in an open source edition. You may wonder which one is the best choice for running GeoServer. In a production environment, usually the same container is shared among several web applications. You are not going to choose the container; the architects and system administrators made their choices and you have to conform to them. As a beginner, you have the opportunity of selecting it! Apache Tomcat should be your first choice as it is widely adopted in the Geoserver developer's community. If you run into any issues, the answer is probably waiting for you in the mailing list archive.

We are going to install Apache Tomcat. It is an open source project of Apache foundation ( and there are reasons for installing it such as it is widely used, well-documented, and relatively simple to configure.

So let's start the Apache Tomcat installation.

Time for action — installing Apache Tomcat on Windows

We will install the Apache Tomcat 7.x release.

On Windows, we will use the installer. It will add an item in the service control panel allowing you to set Tomcat for automatic startup.

  1. Open your browser and visit the download page for 7.x releases at

  2. Select the 32-bit/64-bit Windows Service Installer and save the EXE file to a folder on your machine.

  3. Select the downloaded file and run it as the administrator, then press the Yes button when asked from the User Account control.

  4. You need to agree to the license agreement.

  5. Leave the default components selection unchanged. We don't need the Host Manager nor the web application examples:

  6. Go with the default port number, unless you know there are other services bounded to them. Set the User Name and Password for web administration (for example, tomcat).

  7. If your JRE installation was successful, the installer will prompt you with the right path to it. In case you have more than one JRE/JDK installed, you can choose which one Tomcat will use:

  8. Lastly you have to supply the folder where Tomcat will be installed and then press the Install button:

  9. The installation process will create a Windows service for you. After the installation, it will try to start the Tomcat 7 service. You will now have a new icon on the system tray. From the pop-up menu, you can control the Tomcat, starting and stopping it or accessing the configuration console:

What just happened?

We installed Apache Tomcat as a service on Windows. Your computer is now ready to host the Geoserver web archive.

Time for action — installing Apache Tomcat on Ubuntu

We will install Apache Tomcat 7.x release.

On Ubuntu, you have two alternatives for installing Apache Tomcat. You can use the package manager to get it. At the time of writing, Ubuntu repositories contain the 7.0.26 release of Apache Tomcat for Ubuntu 12.04. I prefer, and we will be following this method in the book, to download the archive and perform a manual installation. You will have full control over the installation and you can choose the appropriate release number. On the other hand, you can't rely on automatic updates for Tomcat.

  1. You may want to read the license agreement:

  2. Download the archive:

    ~$ wget

  3. Extract it in a folder for alternate applications, specific to your server; /opt sounds like a good place.

    ~$ sudo tar xvfz apache-tomcat-7.0.27.tar.gz -C /opt

  4. You need to properly configure Tomcat before you can use it. Go inside the main folder created while extracting the archive; you should see the following structure:

    ~$ ls -lah /opt/apache-tomcat-7.0.27 total 120K drwxr-xr-x 9 root root 4.0K Jun 6 12:16 . drwxr-xr-x 3 root root 4.0K Jun 6 12:16 .. drwxr-xr-x 2 root root 4.0K Jun 6 12:16 bin drwxr-xr-x 2 root root 4.0K Mar 31 16:45 conf drwxr-xr-x 2 root root 4.0K Jun 6 12:16 lib -rw-r--r-- 1 root root 56K Mar 31 16:45 LICENSE drwxr-xr-x 2 root root 4.0K Mar 31 16:44 logs -rw-r--r-- 1 root root 1.2K Mar 31 16:45 NOTICE -rw-r--r-- 1 root root 8.7K Mar 31 16:45 RELEASE-NOTES -rw-r--r-- 1 root root 11K Mar 31 16:45 RUNNING.txt drwxr-xr-x 2 root root 4.0K Jun 6 12:16 temp drwxr-xr-x 7 root root 4.0K Mar 31 16:44 webapps drwxr-xr-x 2 root root 4.0K Mar 31 16:44 work

  5. The bin and conf folders contain the configuration files and the init script you can edit in order to adjust settings. On a new Unix box, you shouldn't have any issues with the default configuration. If you are installing on a server with other services running, you should check the following points:

    1. Default configuration tries to bind the HTTP connector to port 8080. If it is already used for another service, you need to edit the /opt/apachetomcat- 7.0.27/conf/server.xml file. Find the following section:

      <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

    2. You have to replace 8080 with a port number you know is free to use on your system. Be sure to use a port number higher than 1024. You may guess that changing it to port number 80 is a good idea. On one hand, this will enable you to access your Tomcat installation and web application deployed on it from the browser without having to add the :8080 syntax to your HTTP requests. On the other hand, you have to consider that Apache Tomcat is not developed with strong HTTP security in mind, and this configuration may be unsecure if you expose your container on the Internet. Using a proxy is the correct approach to get the same result while retaining security.

    3. Also remember you have to restart Tomcat for any change you make to the configuration files.

    4. In order to access the web interface for administration tasks you need to edit the security settings. Go into the conf folder and edit the tomcatusers. xml file. The following file syntax is quite self-explanatory:

      ~$ sudo vi /opt/apache-tomcat-7.0.27/conf/tomcat-users.xml

    5. Find and uncomment the following section:

      code 16

    6. You also need to add a "manager-gui" role and assign it to a user. You may also want to change the password value. After the editing, the section should looks as follows:

      <!-- <role rolename="tomcat"/> <role rolename="role1"/> <user username="tomcat" password="tomcat" roles="tomcat"/> <user username="both" password="tomcat" roles="tomcat,role1"/> <user username="role1" password="tomcat" roles="role1"/> -->

    7. Start up Tomcat:

      ~$ sudo /opt/apache-tomcat-7.0.27/bin/ start Using CATALINA_BASE: /opt/apache-tomcat-7.0.27 Using CATALINA_HOME: /opt/apache-tomcat-7.0.27 Using CATALINA_TMPDIR: /opt/apache-tomcat-7.0.27/temp Using JRE_HOME: /usr Using CLASSPATH: /opt/apache-tomcat-7.0.27/bin/ bootstrap.jar:/opt/apache-tomcat-7.0.27/bin/tomcat-juli.jar

    8. You succeeded starting the servlet container and you can now see it among the running processes:

      ~$ ps -ef | grep java root 1960 1 5 14:06 pts/0 00:00:01 /usr/ bin/java -Djava.util.logging.config.file=/opt/apachetomcat- 7.0.27/conf/ -Djava.util.logging. manager=org.apache.juli.ClassLoaderLogManager -Djava. endorsed.dirs=/opt/apache-tomcat-7.0.27/endorsed -classpath /opt/apache-tomcat-7.0.27/bin/bootstrap.jar:/opt/apachetomcat- 7.0.27/bin/tomcat-juli.jar -Dcatalina.base=/ opt/apache-tomcat-7.0.27 -Dcatalina.home=/opt/apachetomcat- 7.0.27 temp org.apache.catalina.startup.Bootstrap start

    9. Remove the archive:

      ~$ rm apache-tomcat-7.0.27.tar.gz

What just happened?

We installed Apache Tomcat. We are really close to finishing the installation process. You can now run the Java web application on your server.

Time for action — configuring Tomcat as a service on Ubuntu

On Windows we configured Tomcat as a system service, that is, a program running at boot without any user action. Are you wondering why on Ubuntu you have to manually start Tomcat? You don't. Indeed, the operating system can be configured for automatic start of services. In this section, you will create a script and learn how it works.

  1. Open your preferred editor and enter the following lines. Be sure to launch the editor with sudo as we are going to create a file in a system folder.

    #!/bin/sh ### BEGIN INIT INFO # Provides: tomcat # Required-Start: $local_fs $remote_fs $network $syslog # Required-Stop: $local_fs $remote_fs $network $syslog # Default-Start: 2 3 4 5 # Default-Stop: 0 1 6 # Short-Description: Start/Stop Tomcat v7.0.27 ### END INIT INFO # # /etc/init.d/tomcat # export JAVA_HOME=/usr/lib/jvm/jre1.6.0_37 export PATH=$JAVA_HOME/bin:$PATH export CATALINA_HOME=/opt/apache-tomcat-7.0.27 export JAVA_OPTS="-Djava.awt.headless=true" case $1 in start) sh $CATALINA_HOME/bin/ ;; stop) sh $CATALINA_HOME/bin/ ;; restart) sh $CATALINA_HOME/bin/ sh $CATALINA_HOME/bin/ ;; *) echo "Usage: /etc/init.d/tomcat {start|stop|restart}" exit 1 ;; esac exit 0

  2. The previous script is simple and contains all of the basic elements you will need to get going. Pay attention to the path; you can adjust your script according to your system settings.

  3. Call the new file tomcat and save it in the /etc/init.d folder.

  4. Now, set the permissions for your script to make it executable:

    ~$ sudo chmod a+x /etc/init.d/tomcat

  5. Let's try to call it and check for any problems:

    ~$ sudo service tomcat Usage: /etc/init.d/tomcat {start|stop|restart}

  6. Try starting Tomcat:

    ~$ sudo service tomcat start

  7. Ok, it is running now:

    ~$ ps -ef | grep java root 1960 1 5 14:06 pts/0 00:00:01 /usr/bin/ java -Djava.util.logging.config.file=/opt/apache-tomcat-7.0.27/ conf/ -Djava.util.logging.manager=org.apache. juli.ClassLoaderLogManager -Djava.endorsed.dirs=/opt/apachetomcat- 7.0.27/endorsed -classpath /opt/apache-tomcat-7.0.27/ bin/bootstrap.jar:/opt/apache-tomcat-7.0.27/bin/tomcat-juli.jar -Dcatalina.base=/opt/apache-tomcat-7.0.27 -Dcatalina.home=/opt/ apache-tomcat-7.0.27 temp org.apache.catalina.startup.Bootstrap start

  8. Now stop it:

    ~$ sudo service tomcat stop

  9. Now that you have a working script, the last step is adding to configured services. We will use update-rc:

    ~$ sudo update-rc.d tomcat defaults Adding system startup for /etc/init.d/tomcat ... /etc/rc0.d/K20tomcat -> ../init.d/tomcat /etc/rc1.d/K20tomcat -> ../init.d/tomcat /etc/rc6.d/K20tomcat -> ../init.d/tomcat /etc/rc2.d/S20tomcat -> ../init.d/tomcat /etc/rc3.d/S20tomcat -> ../init.d/tomcat /etc/rc4.d/S20tomcat -> ../init.d/tomcat /etc/rc5.d/S20tomcat -> ../init.d/tomcat

  10. Reboot your system and check if Tomcat is already running.

What just happened?

We created a shell script for starting Apache Tomcat. Now as you boot your Ubuntu machine, Tomcat will be initialized and all the web application content will be available for user requests. If you prefer to manually start and stop Tomcat, the script could yet be useful for you. Just create it as described and avoid the last step. You will use the script to start or stop Tomcat from the command line, that is, sudo tomcat start or sudo tomcat stop.

Have a go hero — exploring the Tomcat web interface

Apache Tomcat ships with a web interface for basic configuration and administration tasks. You are going to use it for installing Geoserver. Open your browser and point to the base main (for example, http://localhost:8080/). Do you remember we edited a file about roles, users, and passwords? You will be presented with an HTTP digest authorization form; try to guess which credentials you have to supply. Explore the manager application.

Installing GeoServer

We are well on our way! Go to the GeoServer site ( and review the installation options available. You'll find several versions of GeoServer. We're going to be using the Web Archive version.

We will deploy the web archive on Apache Tomcat. As you may have guessed, using a Java application server is pretty much the same on any operating system.

Time for action — deploying GeoServer on Tomcat

With Java installed and working, let's install the GeoServer. The latest version is 2.2.

  1. Download the OS-independent version from GeoServer's download page. You can point your browser to the URL or use a command-line tool like wget:

    ~$ wget

  2. Unzip the archive file:

    ~$ unzip The war file for GeoServer is quite big, actually a little more than 52 MByte. In Tomcat 7 Manager there is a default limit for deployable application that is at 50 MByte. You will set it to a safe size for GeoServer. Open the $CATALINA_HOME/webapps/manager/ WEB-INF/web.xml file and look for this section <multipart-config> <!-- 50MB max --> <max-file-size>52428800</max-file-size> <max-request-size>52428800</max-request-size> <file-size-threshold>0</file-size-threshold> </multipart-config>

  3. Set the max-file-size to 62914560 value both in max-file-size and maxrequest-size parameters. Save the file and restart Tomcat.

  4. Point your browser to the application manager at http://localhost:8080/manager/html.

  5. You will be requested to insert a User Name and a Password, if you follow the instructions on installing Tomcat. Insert tomcat as User Name and the same as Password:

  6. Now we are in the application manager, the panel where we control the web application running on our container. Scroll down to the Deploy section:

  7. Press the Browse button in WAR file to deploy and select the geoserver.war file.

  8. Press the Deploy button. After a while you will see the OK response from the manager. Now GeoServer is listed among the web applications deployed in Tomcat.

  9. Click on the /geoserver link shown in the column on the left-hand side of the list. You are now looking at the start page of your brand new GeoServer instance:

What just happened?

We deployed the GeoServer web archive on Tomcat. It unpacked the archive content. If there were no errors in the package, thanks to the great job of GeoServer developers (chances are that you won't find them), then Tomcat automatically starts GeoServer.

Implementing basic security

The web interface shown at http://localhost:8080/geoserver requires you to log in. You can use the default values of admin as username and geoserver as password. The new interface will show you some warning about security issues:

You may ignore the third and fifth warning. It is a good idea to address the others immediately.

Time for action — improving security settings

  1. We will start by changing the default password for the administrator. Click on the Change it link on the left-hand side of the warning.

  2. A new page containing user properties will show up. Insert the new password in the Password and Confirm password textboxes and click on the Save button. You don't need to restart GeoServer or Tomcat; the new password is active now!

  3. The file is a security risk because it contains user passwords in plain text. GeoServer does not need it so it's safe to delete it.

    ~$ sudo rm /opt/apache-tomcat-7.0.27/webapps/geoserver/data/security/

  4. Now open the file. It contains the password generated by GeoServer for the root user. Store it in a secure place and delete the file.

    ~$ sudo rm /opt/apache-tomcat-7.0.27/webapps/geoserver/data/security/

What just happened?

Although you are setting up a development machine, security is always an issue. GeoServer ships with a default administrative password; you logged onto the web interface and changed the default password, then fixed some other issues. You had just a brief taste of the powerful GeoServer's web interface.


We've laid out a basic foundation to get GeoServer up and running.

In this article, you learned how to check whether the Java Runtime Environment (JRE 1.6) is installed and properly working. You also installed Tomcat on Windows and Linux, and configured it to start automatically.

After filling the system requirements, you explored the web archive option to install GeoServer and accessed the administrative interface using a web browser.

The web interface is a very powerful tool and you have to know it well to use all GeoServer's features.

Resources for Article :

Further resources on this subject:

You've been reading an excerpt of:

GeoServer Beginner's Guide

Explore Title