Mastering Geoserver

A well-designed production environment will be as lean as possible in terms of the resources consumed and the overall system footprint; one way to achieve this is to ensure that servers do not contain any more software than is absolutely necessary to deliver its intended function. So, in the case of a server being deployed to deliver mapping services, it should only contain the software necessary to deliver maps.

There are many different flavors of Linux available and all of them are capable of running GeoServer without any issues, after all, Java is cross-platform! The choice of Linux distribution is often either a personal one or a company policy-enforced one. There is a great deal of information available to install GeoServer on a Ubuntu distribution, but very little on installing on a CentOS distribution. CentOS is an enterprise-class distribution that closely follows the development of Red Hat Enterprise Linux, and it is a common installation in organizations. We will use CentOS 6.3, and in keeping with the philosophy of making sure that the server is lean, we will only use the minimal server installation.

By default, CentOS 6.3 comes preinstalled with OpenJDK 1.6 as a result of potential licensing conflicts with the distributing Oracle Java that's preinstalled. The GeoServer documentation states that OpenJDK will work with GeoServer, but there might be issues, particularly with respect to 2D rendering performances. While OpenJDK can be used to run GeoServer, it is worth noting that the project does not run tests of GeoServer against OpenJDK, which means that there is a potential risk of failure if it is used in production.

As mentioned previously, Oracle Java is not packaged for the CentOS platform, and thus we will need to install it ourselves using a generic package direct from Oracle. To download Java, visit the Oracle Technology Network website:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Perform the following steps:

This tells CentOS that any time the java command is used, it actually refers to the binary contained within the Oracle JRE directory and not the OpenJDK binary. The flavor of Java used by the system can be changed any time running the following command:

$ alternatives –-config java

The alternatives command should present you with the following prompt:

There are 2 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java
*+ 2           /usr/java/latest/bin/java

Enter to keep the current selection[+], or type selection number:

Depending on the number of programs configured to provide the java command, you will be presented with a list. The program that is currently responding to java is indicated by an asterisk.

In this case, Oracle JRE, which we just installed, is shown to be the active one. If Oracle JRE is not currently selected, then simply enter the number matching the /usr/java/latest/bin/java entry in your list.

We can now test whether our system is using Oracle JRE issuing the following command:

$ java –version

If all goes well, we should see the following response:

java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)

Your version numbers might differ, but the rest should be the same; most importantly, we do not want to see the word OpenJDK anywhere.

If you target Windows Server in your production environment, life is a little simpler than it is for the users of Linux. For the purposes of this book, we will use Windows Server 2008 R2 SP1 Standard Edition, however other versions of Windows Server that can have Java installed should also work fine.

Once again, we will adopt the best practice to use Oracle JRE, and again we will use Version 1.7. Go ahead and download the Windows package for JRE from Oracle's Technology Network website:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

At this point, we have a decision to make about which JRE installer to download, 32-bit or 64-bit. Making the right decision now is important as the choice of 32-bit versus 64-bit will have consequences later when configuring GeoServer. In the next section, we will discuss the installation of Apache Tomcat, which has a dependency on Java, in order to run GeoServer.

In the Windows environment, the Apache Tomcat installer will automatically install a 32-bit or 64-bit Windows Service based on the installed Java. So, a 64-bit installation of Java will mean that the Apache Tomcat service will also be installed as 64-bit.

The three factors influencing the choice of a 32-bit or 64-bit Java are:

Hopefully, the first reason is self-explanatory. If you have a 32-bit version of Windows installed, you can only install a 32-bit version of Java. If you have a 64-bit Windows installation, then you can choose between the two versions. We install to Windows Server 2008 R2 SP1, which is only available in 64-bit; this means that the processor architecture or Windows is not a limitation. In this case, the decision now comes down to the memory configuration and use of native JAI and JAI Image I/O extensions.

The memory consideration is an important decision since a 32-bit process, irrespective of whether it runs on a 32-bit or 64-bit processor architecture, can only address a maximum of 2 GB memory. Therefore, if we want to maximize the available server memory, we will need to consider using the 64-bit version of Java. However, the JAI and JAI Image I/O extensions are only available on the Windows platform as 32-bit binaries. If we choose the 64-bit Java, then we will not be able to use the extensions, which can be an issue if we plan on using our server to provide predominantly raster datasets. The native JAI and JAI Image I/O extensions can provide a significant performance increase when performing raster operations, in other words, responding to WMS requests.

Getting the most out of a production environment is as much about maximizing resource utilization as anything else. If we have a server with lots of memory, we can use the 64-bit Java and allocate it a large chunk of memory, but then the only real advantage this provides is that it will allow us to do more concurrent raster operations. The maximum number of concurrent requests will still be limited by other factors, which might not be the most efficient use of server resources. An alternative approach is to scale-up by running multiple instances of GeoServer on the server. This is discussed in more detail later in this chapter. Scaling-up means that we can maximize the usage of server resources (memory) without compromising on our ability to utilize the native JAI and JAI Image I/O extensions.

To install the 32-bit version of Java, perform the following steps:

Closing the installation wizard will launch a web browser where the installation of Java can be verified by the steps given on the page loaded after Java installation.

As with all the Linux variants, CentOS has a package management system that can be used to install software, including Apache Tomcat. However, quite often, the packaged software is several versions behind the current version. Unlike other software running on Linux, Tomcat does not actually require compiling, and so installing it directly from Apache is not much of a challenge. Perform the following steps to install Apache Tomcat on CentOS:

This is interesting, but actually not particularly useful in the context of a production environment. In a production environment, we need to be able to set memory parameters for JVM, have Tomcat run as a service on startup, and run the Tomcat service using a user with limited privileges.

Running Apache Tomcat as a service

Security is a key consideration for any production environment, and wherever possible, the applications and services should run using user accounts with just the right level of privileges for them to perform their functions. To adopt this best practice, we will now create a user account under which we can run the Tomcat service:

1. At your command line, enter the following:

   $ sudo groupadd tomcat
   $ sudo useradd –s /bin/bash –g tomcat tomcat

   The first command creates a new user group called tomcat. The second command creates a new user called tomcat, adds this user to the tomcat group, and sets its shell to bash.

2. Now that we have a tomcat user, we need to set the ownership of the Tomcat installation folder to this user:

   $ sudo chown –Rf tomcat:tomcat /opt/apache-tomcat-7.0.50/

3. Now we are ready to create a service control script that will allow us to start, stop, and reload the Tomcat application. To do this, we need to create a service controller script and then register this script with an appropriate run level so that CentOS will start the service on boot:

   $ cd /etc/init.d
   $ sudo vi tomcat-1

   The preceding commands will enter the services directory on CentOS and create a blank script called tomcat-1. The name of the script is not important. However, as we will see later when scaling Tomcat in production, we might want to instantiate multiple services, and so should come up with a suitable naming convention to keep track of them. In this case, we use the convention, tomcat-n, where n will be an incremented number. The vi command will start the vim text editor with an empty file; replace this with whatever your favorite Linux text editor is.

4. In the text editor, enter the following script:

   #!/bin/bash  
   # description: Tomcat 1 Start Stop Restart  
   # processname: tomcat-1  
   # chkconfig: 234 20 80  
   JAVA_HOME=/usr/java/latest  
   export JAVA_HOME  
   PATH=$JAVA_HOME/bin:$PATH  
   export PATH  
   CATALINA_HOME=/opt/apache-tomcat-7.0.50
   JAVA_OPTS="-server –Xmx1024m –Xms512m –XX:MaxPermSize=128m"
   export JAVA_OPTS  
     
   case $1 in  
   start)  
   /bin/su tomcat $CATALINA_HOME/bin/startup.sh  
   ;;   
   stop)     
   /bin/su tomcat $CATALINA_HOME/bin/shutdown.sh  
   ;;   
   restart)  
   /bin/su tomcat $CATALINA_HOME/bin/shutdown.sh  
   /bin/su tomcat $CATALINA_HOME/bin/startup.sh  
   ;;   
   esac      
   exit 0

There is quite a lot going on in this script, so let's break it down a little. The first four lines beginning with a hash (#) are settings for how the script is run. The last line in this group indicates the run levels that this service will operate under (234) and the stop and start priorities (20 and 80). This information tells the chkconfig command how to run the service.

Next, the script will set environment variables to tell the system where to find Java (JAVA_HOME), making the java command accessible on the command line (PATH) and setting the Tomcat directory (CATALINA_HOME). Next, we set an environment variable called JAVA_OPTS, which provides parameters to run JVM. This is where we can specify the memory configuration for our GeoServer instance. There is a discussion on how to determine the most appropriate memory settings for your server later in this book; for now, we will use settings that are good for an all-rounder instance of GeoServer.

The following table describes what each of these parameters are and why they are set:

Parameter	Description
-server	This parameter tells JVM to run in the server mode, which enables it to compile the optimized byte code early. Initial calls will be slow because of longer Just-In-Time (JIT) compiling, but subsequent calls will be faster.
-Xmx1024m	This parameter tells JVM the maximum amount of heap memory it can allocate. In this case, JVM will allocate a maximum of 1 GB of memory.
-Xms512m	This parameter tells JVM how much heap memory to allocate on startup. This will ensure that memory management is more stable. In this case, we tell JVM to allocate 512 MB heap on startup.
-XX:MaxPermSize=128m	This parameter sets the maximum size of the permanent generation (also known as permgen) allocated for GeoServer. Permgen is where the class byte code is stored. In applications that use a lot of classes, such as GeoServer, it will exhaust the default JVM allocation quickly, leading to permgen memory errors.

The final section of the script is a case statement that will perform different actions according to the first parameter (case $1) passed to the script. This can be one of start, stop, or restart. In each case, the Tomcat startup.sh and/or shutdown.sh scripts are executed.

Now we have our service script created, we need to set appropriate permissions on it, using the following command:

$ sudo chmod 755 tomcat-1

Once the script is executed, we can register it in CentOS as a service. The chkconfig utility is used to register the script as a service:

$ sudo chkconfig --add tomcat-1
$ sudo chkconfig --level 234 tomcat-1 on

The first line adds our script, and the second line sets the runtime levels for it. We can check the configuration to make sure it is registered correctly:

$ sudo chkconfig --list tomcat-1
tomcat-1        0:off   1:off   2:on    3:on    4:on    5:off   6:off

If all goes well, levels 2, 3, and 4 will be marked as on, with all other levels marked off. From this point onward, every time our server restarts, it will automatically run the tomcat-1 service, thereby giving us Tomcat on each boot.

We should now check that the script works as expected, trying each of the following commands in turn:

$ sudo service tomcat-1 start
Using CATALINA_BASE:   /opt/apache-tomcat-7.0.50
Using CATALINA_HOME:   /opt/apache-tomcat-7.0.50
Using CATALINA_TMPDIR: /opt/apache-tomcat-7.0.50/temp
Using JRE_HOME:        /usr/java/latest
Using CLASSPATH:       /opt/apache-tomcat-7.0.50/bin/bootstrap.jar:/opt/apache-tomcat-7.0.50/bin/tomcat-juli.jar

$ sudo service tomcat-1 restart
Using CATALINA_BASE:   /opt/apache-tomcat-7.0.50
Using CATALINA_HOME:   /opt/apache-tomcat-7.0.50
Using CATALINA_TMPDIR: /opt/apache-tomcat-7.0.50/temp
Using JRE_HOME:        /usr/java/latest
Using CLASSPATH:       /opt/apache-tomcat-7.0.50/bin/bootstrap.jar:/opt/apache-tomcat-7.0.50/bin/tomcat-juli.jar
Using CATALINA_BASE:   /opt/apache-tomcat-7.0.50
Using CATALINA_HOME:   /opt/apache-tomcat-7.0.50
Using CATALINA_TMPDIR: /opt/apache-tomcat-7.0.50/temp
Using JRE_HOME:        /usr/java/latest
Using CLASSPATH:       /opt/apache-tomcat-7.0.50/bin/bootstrap.jar:/opt/apache-tomcat-7.0.50/bin/tomcat-juli.jar

$ sudo service tomcat-1 stop
Using CATALINA_BASE:   /opt/apache-tomcat-7.0.50
Using CATALINA_HOME:   /opt/apache-tomcat-7.0.50
Using CATALINA_TMPDIR: /opt/apache-tomcat-7.0.50/temp
Using JRE_HOME:        /usr/java/latest
Using CLASSPATH:       /opt/apache-tomcat-7.0.50/bin/bootstrap.jar:/opt/apache-tomcat-7.0.50/bin/tomcat-juli.jar

If everything works as expected, we will see a similar output. Start the Tomcat service again if it is not already running, and then navigate to the server's IP address or the URL. We should get the Tomcat web page like the one shown in the following screenshot:

Congratulations! We now have CentOS 6.3 running Java and Apache Tomcat with the Tomcat service automatically, starting each time the server boots. Go ahead and restart the server to check that the Tomcat service starts automatically.

<?xml version="1.0" encoding="utf-8">
<tomcat-users>
  <role rolename="manager-gui" />
  <user username="r2d2" password="5t4rW4r5" roles="manager-gui" />
</tomcat-users>

$ sudo service tomcat-1 restart

Once again, Windows users get the convenience of an installation wizard to take care of installing Tomcat. For the Windows installation package, choose the 32bit/64bit Windows Service Installer option. Download the installation file to a directory on your local hard drive.

To install Tomcat, perform the following steps:

Tomcat is now installed as Windows Service, which we can control like any other service.

Controlling the Tomcat service

The Windows version of Tomcat comes with an application called Monitor Tomcat, which starts automatically each time you log on to Windows. It is a System Tray application that allows quick access to monitor and manage the running Tomcat service.

Notice the icon in the top-left corner of System Tray; this is the Monitor Tomcat application and its icon tells us that Tomcat is not currently running (indicated by the red square in the middle).

If the Tomcat service runs, it displays a green triangle on its side, like a "play" symbol. If we right-click on the Monitor Tomcat application icon, we get a context menu as shown in the following screenshot:

The context menu provides us with the ability to access the Tomcat service configuration and allows us to stop and start the service without the need to go through the normal Windows service applet. Of course, Tomcat still runs as a normal Windows service, so there is nothing stopping us to manage it in the normal way; the Monitor Tomcat application is just a convenience tool.

Configuring the Tomcat service

Before we start the Tomcat service to check our installation is alright, we must configure the memory settings that Tomcat will use for Java VM. Right-click on the Monitor Tomcat application icon and select the Configure… menu item to open the Tomcat service configuration dialog. Once it is open, click on the Java tab at the top:

The Java tab allows us to set options that control the way Tomcat starts Java VM; the most important of these, from our perspective, is the memory configuration. Memory settings can be specified in one of the following two ways:

• Parameters in the Java Options textbox

• Entering values in Initial memory pool, Maximum memory pool, and Thread stack size

The choice is merely one of the preferences as both will achieve the same effect. My personal preference is to put everything into the Java Options textbox as it is good to remind oneself of the correct Java option parameter names, especially if you have a mixed Linux/Windows server environment.

The actual values to use for memory settings are subjects that we will cover later in this book, and we will very much depend on how you intend to use your GeoServer in production. For example, if you only intend serving vector data (through WFS), then GeoServer requires very little by way of memory allocation. For now, we will set the memory to some good defaults for an all-rounder GeoServer. Click on the Java Options textbox and scroll to the last parameter, press Enter to start a new line, and then enter the following parameters:

-Dserver
-Xmx1024m
-Xms512m
-XX:MaxPermSize=128m

Note

These parameters and what their values mean are described in the table given in the Running Apache Tomcat as a service section of this chapter.

With the Java options set, we are now ready to fire up the Tomcat service and check everything as is expected. Click on the General tab, then on the big Start button, and cross your fingers as the service starts up. If everything works, then the Start button will be disabled and the Stop button will be enabled. If the Start button is enabled again, and the Stop button remains disabled, then unfortunately something is wrong. Check that all the option parameters are correct and then try again. If you still don't get the service starting, check the Tomcat logs to try and figure out why.

If all goes well, we should be able to open a browser window, navigate to http://localhost:8080/, and get the Tomcat 7 web page, as shown in the following screenshot:

Tomcat 7 web page

That's it! Java and Tomcat are now both configured on your Windows Server, and it is now ready to take the GeoServer application.

Deployment of GeoServer on CentOS is a very straightforward process, thanks to the way Tomcat is architected. WAR files can automatically be deployed by copying them to a specific location in the Tomcat home directory.

Download the WAR file to a location on your system, for example, your home directory:

$ cd ~
$ wget http://sourceforge.net/projects/geoserver/files/GeoServer/2.5.2/geoserver-2.5.2-war.zip

The WAR file that we want to deploy to GeoServer is contained within the downloaded ZIP file, so we need to extract this from the Tomcat appBase directory:

$ sudo unzip geoserver-2.5.2-war.zip *.war –d $CATALINA_HOME/webapps/

This command will only extract the geoserver.war file from the ZIP file and place it in the Tomcat appBase directory. Tomcat will then autodeploy the WAR file, and you should see a geoserver directory appear.

Deploying the GeoServer WAR file on Windows follows the same process as that of Linux. The WAR file is copied in the Tomcat home directory, where it is unpacked and the GeoServer context started.

The following steps are required to deploy the GeoServer WAR file in Tomcat:

We should now have a basic configuration of GeoServer deployed inside an Apache Tomcat instance. Test that GeoServer was successfully deployed by opening a web browser and navigating to the GeoServer administration interface:

http://[your server address]:8080/geoserver

If everything worked as expected, then we should be presented with the GeoServer administration interface's front page:

Scaling vertically, also known as scaling up, is when additional resources are added to a single (physical or virtual) node. In other words, this is when you create more than one instance of GeoServer to run on the same physical or virtual server. The following diagram depicts scaling vertically:

The available resources on the server are maximized by running multiple instances of GeoServer. Consistency of data is maintained across each of the instances by all of them sharing a common data directory, either located on the node itself or elsewhere on the network.

Traffic is managed across the GeoServer instances by a load balancer that can be a physical one in the network or even a software-based one.

Scaling horizontally, also known as scaling out, is when you add additional nodes (physical or virtual) to your environment. Each additional node can have an instance of GeoServer running on it. The following diagram depicts scaling horizontally:

Increased capacity is provided by the additional nodes running GeoServer, and the traffic across them is managed through a physical load balancer in the network.

In a scaled-out architecture, the data directory for GeoServer is shared across the additional nodes to ensure consistency of the configurations. With this approach, you can choose to place the shared data directory on one of the nodes and allow access to the additional nodes, or you can choose to have a separate server to hold shared data such as a Network Attached Storage (NAS) device.

To really get the best performance from your production environment, it is worth considering scaling GeoServer both vertically and horizontally. Increase the capacity of your environment through additional nodes, and then maximize the resources on each node by running multiple instances of GeoServer. The following diagram depicts scaling vertically as well as horizontally:

In this architecture, traffic to each of the GeoServer instances running on each node is managed through a physical load balancer on the network. The load balancer can be configured to register one of the GeoServer nodes as the failover node, ensuring continuity of service should one or more of the primary nodes fail.

Once again, a shared data directory is used across the nodes to ensure consistency, but in this case, it will definitely make sense to keep the directory on a separate server instance.

First, we need to create a copy of our Tomcat installation directory:

$ sudo cp –R /opt/apache-tomcat-7.0.50/ /opt/apache-tomcat-7.0.50-2

This command will copy our installation directory to the same location and append 2 to the end. The name and location of the directory does not matter; just ensure that it has a different name so that you can distinguish it from others. Next, we need to make the tomcat user the owner of the new directory:

$ sudo chown –Rf tomcat:tomcat /opt/apache-tomcat-7.0.50-2/

Then we need to configure the Tomcat instance so that it can co-exist with other instances. This involves altering the server.xml file stored in the conf folder of the copied installation. Edit the file with your favorite text editor, and look for the line containing the following:

<Server port="8005" shutdown="SHUTDOWN">

Change the value of the port attribute to 8006 by incrementing it by 1. Further down the file, look for the line containing:

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

Change the value of the port attribute to 8081 by incrementing it by 1, save the file, and exit the text editor. We also need to change the value of redirectPort, again incrementing it by 1 to make it 8444. What we just did has changed the ports on which the Tomcat service will listen for connections. Failing to do this will generate an error when we try to start the Tomcat service. If we want to add more Tomcat instances, we just need to follow the same process; increment each value by 1 again.

Next, we need to copy our data directory out to a location where each instance can share it. For this, we will make a new directory:

$ sudo mkdir /mnt/share
$ sudo cp –R /opt/apache-tomcat-7.0.50/webapps/geoserver/data/ /mnt/share/geoserver-data
$ sudo chown –Rf tomcat:tomcat /mnt/share/geoserver-data/

Now, we created a directory to share amongst our instances, copied our original GeoServer data directory into it, and then made the tomcat user the owner of the directory.

You might be wondering why we just copied the data directory out to a different location. This is an important step for two reasons:

The last point is an important one. Even if we only run a single instance of GeoServer, it is a good practice to place the data directory outside of the GeoServer installation. When we decide to upgrade, we can do so by simply deploying a new WAR file without having to back up and restore the original data directory.

Now we can make a new service for our newly configured instance:

$ sudo cp /etc/init.d/tomcat-1 /etc/init.d/tomcat-2

Next, we need to make some changes to the service script to tell each GeoServer instance where the data directory is located, and we will also control the name and location of the default logfile for GeoServer. Edit the tomcat-1 and tomcat-2 script files in your favorite text editor, and add the following lines near the start:

GEOSERVER_DATA_DIR=/mnt/share/geoserver-data
export GEOSERVER_DATA_DIR

This line sets an environment variable for our external data directory. Next, add the following lines:

GEOSERVER_LOG_LOCATION=$GEOSERVER_DATA_DIR/logs/geoserver-1.log
export GEOSERVER_LOG_LOCATION

This sets another environment variable, but this time it tells GeoServer what to call the logfile that will be generated. This is another important aspect of running multiple instances of GeoServer, and it is essential to avoid clashes on the logging.

Do the same for both the service scripts, but change the name of the logfile to suit each instance. Now we just need to register the second service script so that it can be controlled:

$ sudo chkconfig --add tomcat-2
$ sudo chkconfig --level 234 tomcat-2 on
$ sudo service tomcat-1 restart
$ sudo service tomcat-2 start

That's it! Now, we have two instances of GeoServer running on our server and sharing a common data directory. You can test it by opening a web browser and visiting the following:

Once again, life is a little simpler in the world of Windows. All we need to do is configure some environment variables to set the location of the shared data directory and the name and location of the logfile, and then create a new service instance. First, copy the current GeoServer data directory (C:\Tomcat7-1\webapps\geoserver\data) to a location outside of the container, for example, D:\Data\geoserver-data. Then, click on the Windows Start button, right-click on Computer, and choose the Properties menu option:

In the System Properties dialog that opens, click on the link at the left-hand side labelled Advanced system settings, and in the dialog box that opens, click on the Advanced tab. Click on the button labelled Environment Variables… to open a new properties dialog:

Click on the New button in the System variables group, and then enter the details shown in the preceding screenshot. Click on Ok to dismiss all of the dialogs. We now have an environment variable to tell GeoServer where to find its data directory.

Next, we need to create a new instance of the Tomcat service. To do this, we just need to rerun the installation file that we downloaded originally. Work through all of the pages until you reach the Configuration Options page:

On this page, we need to change the settings for the ports by incrementing the default values by 1, for example, HTTP/1.1 Connector Port will be 8081 instead of 8080. We also need to change the default value of Windows Service Name, in this case, we continue with our naming convention of incrementing each instance by 1. Click on Next to check whether the Java installation directory is correct, and then click on Next again to specify where we want to install the files. Change the installation location so that it points to C:\Tomcat7-2.

Now we need to use the Tomcat Monitor application to control the new service. Copy the same values for the Java options, but also include an additional parameter to tell GeoServer where to create its logfile this time:

-DGEOSERVER_LOG_LOCATION=D:\Data\geoserver-data\logs\geoserver-2.log

We created a second instance of Tomcat, so we just need to deploy the geoserver.war file to it by copying it into the C:\Tomcat7-2\webapps folder and letting Tomcat perform autodeploy when it starts up.

Remember to include –DGEOSERVER_LOG_LOCATION in the original Tomcat instance Java options, and specify the name of a logfile so that it can be distinguished. Then, restart both the new services. If everything works as expected, you can open a browser and navigate to: