GeoServer Cloud

GeoServer Cloud is GeoServer ready to use in the cloud through dockerized microservices.

This project is an opinionated effort to split GeoServer's geospatial services and API offerings as individually deployable components of a microservices based architecture.

As such, it builds on top of existing GeoServer software components, adapting and/or extending them in an attempt to achieve functional decomposition by business capability; which roughly means each OWS service, the Web UI, the REST API, and probably other components such as the Catalog and Configuration subsystem, become self-contained, individually deployable and scalable micro-services.

Quick start

You can easily deploy and test locally GeoServer Cloud after cloning this repository on your computer by running the following command:

docker-compose -f docker-compose.yml -f docker-compose-shared_datadir.yml up -d

This will start a GeoServer Cloud stack using a file based backend as catalog system.

Browse to http://localhost:9090/geoserver/cloud to access the GeoServer UI.

Architecture

The following diagram depicts the system's general architecture.

GeoServer Cloud Architecture Diagram

Does that mean GeoServer's .war is deployed several times, with each instance exposing a given "business capability"? ABSOLUTELY NOT. Each microservice is its own self-contained application, including only the GeoServer dependencies it needs. Moreover, care has been taken so that when a dependency has both required and non-required components, only the required ones are loaded.

Technology

With GeoServer being a traditional, Spring Framework based, monolithic servlet application, a logical choice has been made to base the GeoServer derived microservices in the Spring Boot framework.

Additionally, Spring Cloud technologies enable crucial capabilities such as dynamic service discovery, externalized configuration, distributed events, API gateway, and more.

Only a curated list of the vast amount of GeoServer extensions will be supported, as they are verified and possibly adapted to work with this project's architecture. The current version supports the following extensions:

• jdbc config
• jdbc store
• pgraster
• datadir-catalog-loader
• authkey authentication
• web-resource explorer
• css style
• mb style
• GWC S3 Storage
• GWC Azure Blob Storage
• Pregeneralized feature datastore
• vectortiles
• flatgeobuf
• cog
• importer

Advanced ACL system is available through the project GeoServer ACL which offers the same capacities as GeoFence.

OAuth is available by using the geOrchestra Gateway in replacement of the GeoServer Cloud one.

License

GeoServer Cloud licensed under the GPLv2.

Building

Requirements:

• Java >= 17 JDK
• Maven >= 3.6.3
• Docker version >= 19.03.3
• docker-compose version >= 1.26.2

The simple make command from the project root directory will build and install all the required components, including upstream GeoServer dependencies and GeoServer-Cloud Docker images. So for a full build just run:

make

Then for further builds, unless the geoserver_submodule/ has changed, you can build without running tests with

make install

and run tests with

make test

Custom upstream GeoServer version

GeoServer Cloud depends on a custom GeoServer branch, gscloud/gs_version/integration, which contains patches to upstream GeoServer that have not yet been integrated into the mainstream main branch.

Additionally, this branch changes the artifact versions from 2.23-SNAPSHOT to 2.23.0-CLOUD, to avoid confusing maven if you also work with vanilla GeoServer, and to avoid your IDE downloading the latest 2.23-SNAPSHOT artifacts from the OsGeo maven repository, overriding your local maven repository ones, and having confusing compilation errors that would require re-building the branch we need.

The gscloud/gs_version/integration branch is checked out as a submodule under the geoserver_submodule/geoserver directory.

The root pom.xml defines a geoserver maven profile, active by default, that includes the module geoserver_submodule, which in turn includes all the required geoserver modules for this project.

So in general, you may choose to only eventually build the geoserver_submodule subproject, since it won't change frequently, with

make deps

Build the docker images

As mentioned above, a make with no arguments will build everything.

But to build only the docker images, run:

make build-image

Targeted builds

GeoServer Cloud-specific modules source code is under the src/ directory.

When you already have the 2.23.0-CLOUD GeoServer artifacts, you can choose to only build these projects, either by:

$ ./mvnw clean install -f src/

Or

$ cd src/
$ ../mvnw clean install

Development runs

To run the development docker composition using a shared data directory.

GeoServer-Cloud can start from an empty directory.

Edit your .env file to set the GS_USER variable to your user id and group, then do:

$ mkdir docker-compose_datadir
$ alias dcd="docker-compose -f docker-compose.yml -f docker-compose-shared_datadir.yml"
$ dcd up -d

Note: In case you want to start the docker composition and be able to test some layers, you can copy data/release datadir that is part of the geoserver_submodule instead of creating the docker-compose_datadir emtpy folder, as follows:

$ cp -rf ./geoserver_submodule/geoserver/data/release /tmp/datadir
$ ln -s /tmp/datadir docker-compose_datadir

Verify the services are running with dcd ps.

Healthchecks use curl hitting the http:localhost:8081/actuator/health.

The services run on the 8080 port, and are exposed using different host ports. The spring-boot-actuator is set up at port 8081.

The gateway-service proxies requests from the 9090 local port:

$ curl "http://localhost:9090/geoserver/cloud/ows?request=getcapabilities&service={WMS,WFS,WCS}"
$ curl -u admin:geoserver "http://localhost:9090/geoserver/cloud/rest/workspaces.json"

Browse to http://localhost:9090/geoserver/cloud/

Note the /geoserver/cloud context path is set up in the gateway-service's externalized configuration, and enforced through the GEOSERVER_BASE_PATH in docker-compose.yml. You can change it to whatever you want. The default config/gateway-service.yml configuration file does not set up a context path at all, and hence GeoServer will be available at the root URL.

To test GeoServer Cloud with different catalog backends, change the alias to replace the docker-compose-shared_datadir.yml file by one of the following:

• Use docker-compose-jdbcconfig.yml for a JDBC based catalog backend (uses jdbc config and jdbc store modules)
• Use docker-compose-pgconfig.yml for a JNDI based catalog backend

You can also run docker-compose -f docker-compose.yml -f docker-compose-discovery-ha.yml to run extra discovery service instances for HA.

Deployment

Docker images for all the services are available on DockerHub, under the GeoServer Cloud organization (https://hub.docker.com/u/geoservercloud/).

You can find production-suitable deployment files for docker-compose and podman under the docs/deploy folder.

Also, a ready-to-use Helm chart for Kubernetes is available at the camptocamp/helm-geoserver-cloud Github repository.

Contributing

Please read the contribution guidelines before contributing pull requests to the GeoServer Cloud project.

Follow the developer's guide to know more about the project's technical details.

Status

v1.3.0 released against GeoServer 2.23.2.

Read the changelog for more information.

Bugs

GeoServer Cloud's issue tracking is at this GitHub repository.

Roadmap

Follow the development progress on these GitHub Kanban boards