22.2. Installing GeoMesa Lambda

22.2.1. Installing from the Binary Distribution

GeoMesa Lambda artifacts are available for download or can be built from source. The easiest way to get started is to download the most recent binary version (3.0.0) from GitHub.

Extract it somewhere convenient:

# download and unpackage the most recent distribution:
$ wget "https://github.com/locationtech/geomesa/releases/download/geomesa_2.11-$VERSION/geomesa-lambda_2.11-$VERSION-bin.tar.gz"
$ tar xvf geomesa-lambda_2.11-$VERSION-bin.tar.gz
$ cd geomesa-lambda_2.11-$VERSION
$ ls
bin/  conf/  dist/  docs/  examples/  lib/  LICENSE.txt  logs/

22.2.2. Building from Source

GeoMesa Lambda may also be built from source. For more information refer to Building from Source in the developer manual, or to the README.md file in the the source distribution. The remainder of the instructions in this chapter assume the use of the binary GeoMesa Lambda distribution. If you have built from source, the distribution is created in the target directory of geomesa-lambda/geomesa-lambda.

More information about developing with GeoMesa may be found in the Developer Manual.

22.2.3. Installing the Accumulo Distributed Runtime Library

The Lambda data store requires the Accumulo data store distributed runtime to be installed. See Installing the Accumulo Distributed Runtime Library.

22.2.4. Setting up the Lambda Command Line Tools

GeoMesa comes with a set of command line tools located in geomesa-lambda_2.11-$VERSION/bin/ of the binary distribution.

22.2.4.1. Configuring the Classpath

GeoMesa needs Accumulo, Hadoop and Kafka JARs on the classpath. These are not bundled by default, as they should match the versions installed on the target system.

If the environment variables ACCUMULO_HOME, HADOOP_HOME and KAFKA_HOME are set, then GeoMesa will load the appropriate JARs and configuration files from those locations and no further configuration is required. Otherwise, you will be prompted to download the appropriate JARs the first time you invoke the tools. Environment variables can be specified in conf/*-env.sh and dependency versions can be specified in conf/dependencies.sh.

In order to run map/reduce jobs, the Hadoop *-site.xml configuration files from your Hadoop installation must be on the classpath. If HADOOP_HOME is not set, then copy them into geomesa-lamdba_2.11-$VERSION/conf.

GeoMesa also provides the ability to add additional JARs to the classpath using the environmental variable $GEOMESA_EXTRA_CLASSPATHS. GeoMesa will prepend the contents of this environmental variable to the computed classpath, giving it highest precedence in the classpath. Users can provide directories of jar files or individual files using a colon (:) as a delimiter. These entries will also be added the the map-reduce libjars variable.

Note

See Logging Configuration for information about configuring the SLF4J implementation.

Due to licensing restrictions, dependencies for shape file support must be separately installed. Do this with the following command:

$ ./bin/install-shapefile-support.sh

Test the command that invokes the GeoMesa Tools:

$ geomesa-lambda
Usage: geomesa-lambda [command] [command options]
  Commands:
  ...

Note

GeoMesa Accumulo command-line tools can be used against features which have been persisted to Accumulo. See Setting up the Accumulo Command Line Tools for details on the Accumulo command-line tools.

22.2.5. Installing GeoMesa Lambda in GeoServer

Warning

See GeoServer Versions to ensure that GeoServer is compatible with your GeoMesa version.

22.2.5.1. Installing GeoServer

As described in section GeoMesa and GeoServer, GeoMesa implements a GeoTools-compatible data store. This makes it possible to use GeoMesa as a data store in GeoServer. GeoServer’s web site includes installation instructions for GeoServer.

After GeoServer is installed, you may install the WPS plugin if you plan to use GeoMesa processes. The GeoServer WPS Plugin must match the version of the GeoServer instance. The GeoServer website includes instructions for downloading and installing the WPS plugin.

Note

If using Tomcat as a web server, it will most likely be necessary to pass some custom options:

export CATALINA_OPTS="-Xmx8g -XX:MaxPermSize=512M -Duser.timezone=UTC \
-server -Djava.awt.headless=true"

The value of -Xmx should be as large as your system will permit. Be sure to restart Tomcat for changes to take place.

22.2.5.2. Installing the GeoMesa Lambda Data Store

To install the GeoMesa data store, extract the contents of the geomesa-lambda-gs-plugin_2.11-$VERSION-install.tar.gz file in geomesa-lambda_2.11-$VERSION/dist/geoserver/ in the binary distribution or geomesa-lambda/geomesa-lambda-gs-plugin/target/ in the source distribution into your GeoServer’s lib directory:

$ tar -xzvf \
  geomesa-lambda_2.11-$VERSION/dist/gs-plugins/geomesa-lambda-gs-plugin_2.11-$VERSION-install.tar.gz \
  -C /path/to/geoserver/webapps/geoserver/WEB-INF/lib

Next, install the JARs for Accumulo, Hadoop and Kafka. By default, JARs will be downloaded from Maven central. You may override this by setting the environment variable GEOMESA_MAVEN_URL. If you do no have an internet connection you can download the JARs manually via http://search.maven.org/.

Edit the file geomesa-lambda_2.11-$VERSION/conf/dependencies.sh to set the versions of Accumulo, Hadoop and Kafka to match the target environment, and then run the script:

$ ./bin/install-dependencies.sh /path/to/geoserver/webapps/geoserver/WEB-INF/lib

Warning

Due to a classpath conflict with GeoServer, the version of Accumulo client JARs installed must be 1.9.2 or later. Note that newer Accumulo clients can talk to older Accumulo instances, so it is only necessary to upgrade the client JARs in GeoServer, but not the entire Accumulo cluster.

Warning

GeoServer ships with an older version of commons-text, 1.4. The install-dependencies.sh script will remove it, but if you don’t use the script you will need to delete it manually.

The specific JARs needed for some common configurations are listed below:

Accumulo 1.7+

  • accumulo-core-1.7.1.jar
  • accumulo-fate-1.7.1.jar
  • accumulo-server-base-1.7.1.jar
  • accumulo-trace-1.7.1.jar
  • accumulo-start-1.7.1.jar
  • libthrift-0.9.1.jar
  • zookeeper-3.4.6.jar
  • htrace-core-3.1.0-incubating.jar
  • commons-vfs2-2.1.jar

Hadoop 2.2

  • commons-configuration-1.6.jar
  • hadoop-auth-2.2.0.jar
  • hadoop-client-2.2.0.jar
  • hadoop-common-2.2.0.jar
  • hadoop-hdfs-2.2.0.jar

Hadoop 2.4-2.7 (adjust versions as needed)

  • commons-configuration-1.6.jar
  • hadoop-auth-2.6.4.jar
  • hadoop-client-2.6.4.jar
  • hadoop-common-2.6.4.jar
  • hadoop-hdfs-2.6.4.jar

Kafka 0.9.0.1

  • kafka_2.11-0.9.0.1.jar
  • kafka-clients-0.9.0.1.jar”
  • zookeeper-3.4.5.jar”
  • zkclient-0.7.jar”
  • metrics-core-2.2.0.jar

Restart GeoServer after the JARs are installed.

22.2.5.3. GeoMesa Process

Note

Some GeoMesa-specific WPS processes such as geomesa:Density, which is used in the generation of heat maps, also require geomesa-process-wps_2.11-$VERSION.jar. This JAR is included in the geomesa-lambda_2.11-$VERSION/dist/gs-plugins directory of the binary distribution, or is built in the geomesa-process module of the source distribution.

22.2.6. Upgrading

To upgrade between minor releases of GeoMesa, the versions of all GeoMesa components must match. This means that the version of the geomesa-distributed-runtime JAR installed on Accumulo tablet servers must match the version of the geomesa-plugin JARs installed in the WEB-INF/lib directory of GeoServer.

See Upgrade Guide for more details on upgrading between versions.