Stratus is a Spring Boot packaging of Geoserver (currently targeting 2.16) that is designed for Enterprise/Cloud deployments. Due to the magic of Spring and Maven, Stratus doesn't actually change any of the core code of the GeoServer community project. It instead declares (some) of those modules as dependencies and rewires parts of the runtime configuration to use custom pieces.
Stratus has the following main differences from community GeoServer:
- The web administration interface has been removed from all Stratus instances in the cluster. A single instance with the web UI will be deployed for times when the administrative tasks need to be performed with the UI.
- The standard XML file based catalog and resource stores are replaced with a Redis based ones. They intentionally do not cache any resources but instead fetch configuration from the catalog on each request. Ideally this renders Stratus stateless and scalable.
- Stratus uses an embedded Tomcat 8 rather than building a WAR file (however it is still possible to build one)
- Maven 3
- Java 8+
- Docker
Build Stratus jar using:
cd src
mvn clean install -DskipTests
If you wish to enable GDAL support in Stratus, build using:
cd src
mvn clean install -Dgdal
Build Stratus docker image using:
cd src/stratus-application
mvn docker:build
To enable GDAL support while running Strats in docker, you must first build the custom docker base image which includes the GDAL binaries:
cd build/docker/amazonlinux-gdal-py-java11
docker build -t amazonlinux-gdal-py-java11 .
The GDAL-enabled Stratus docker image can then be built using:
cd src/stratus-application
mvn docker:build -Dgdal
For more details on building and developing Stratus, refer to the stratus-application submodule.
Stratus makes extensive use of Lombok, download from https://projectlombok.org/download
and run java -jar lombok.jar to launch the installer. Restart eclipse and run Project/clean/clean all projects.
Requires: Java 8, Local Redis instance
The Stratus jar can be executed with the command java -jar stratus.jar.
Alternatively, you can run Stratus from source from the stratus-application subfolder using mvn spring-boot:run.
Redis is the only dependency required for Stratus to run. By default, it will attempt to connect to a Redis server at localhost:6379.
The deploy/standalone directory contains several useful scripts to start various supporting services, including Redis, PostGIS, and Stratus itself.
By default, Stratus will start with a configuration that excludes all web components and backup/restore dependencies.
To enable the web admin UI, be sure to set the property stratus.admin-enabled or environment variable
STRATUS_ADMIN_ENABLED to true.
By default, Stratus will start using the redis-manual profile which will attempt to connect to a single Redis host.
The following profiles are available:
| Profile | Description |
|---|---|
| jedis-manual | Attempts to connect to a single Redis instance using the Jedis client |
| lettuce-manual | Attempts to connect to a single Redis instance using the Lettuce client |
| jedis-sentinel | Attempts to connect to a Redis Sentinel host using the Jedis client |
| lettuce-sentinel | Attempts to connect to a Redis Sentinel host using the Lettuce client |
| jedis-cluster | Attempts to connect to a Redis Cluster using the Jedis client |
| lettuce-cluster | Attempts to connect to a Redis Cluster using the Lettuce client |
| jedis-aws-tag-discovery | Attempts to connect to Redis using metadata provided by AWS tags using the Jedis client |
| lettuce-aws-tag-discovery | Attempts to connect to Redis using metadata provided by AWS tags using the Lettuce client |
| cloud | Used by PCF to connect to a Redis service |
By default, running Stratus with no parameters will attempt to connect to a single Redis host on
localhost:6379. The following configuration properties can be specified as command line parameters or
environment variables.
| Property | Shortcut | Profile | Default Value | Description |
|---|---|---|---|---|
| stratus.catalog.redis.manual.host | redis-host | {jedis/lettuce}-manual | localhost | The Redis host to connect to. |
| stratus.catalog.redis.manual.port | redis-port | {jedis/lettuce}-manual | 6379 | The Redis port to connect to. |
| stratus.catalog.redis.manual.database | redis-database | {jedis/lettuce}-manual | 0 | The Redis database to connect to. |
| stratus.catalog.redis.sentinel.master | sentinel-master | {jedis/lettuce}-sentinel | mymaster | The name of the Sentinel master. |
| stratus.catalog.redis.sentinel.hosts | sentinel-hosts | {jedis/lettuce}-sentinel | localhost:26379 | A list of Sentinel hosts. |
| stratus.catalog.redis.cluster.hosts | cluster-hosts | {jedis/letuce}-cluster | localhost:6379 | A list of Redis cluster nodes. |
Passing in custom properties depends on how you are running Stratus. Below are examples using java and maven from the command line:
Set the active profile:
- java:
java -jar -Dspring.profiles.active=redis-sentinel stratus.jar - maven:
mvn spring-boot:run -Dspring-boot.run.profiles=lettuce-sentinel
Set the server port:
- java:
java -jar -Dserver.port=8081 stratus.jar - maven:
mvn spring-boot:run -Dserver.port=8081
In addition, properties can be set via environment variables. The variable names should follow the following rules:
- Strictly use all uppercase
- Replace all periods in the property path with underscores
- Separate camelcase variables with underscore where the case changes
Example:
| Stratus Property Name | Environment Variable Name |
|---|---|
| test | TEST |
| spring.profiles.active | SPRING_PROFILES_ACTIVE |
| sentinel-master | SENTINEL_MASTER |
| stratus.catalog.redis.caching.useParallelQueries | STRATUS_CATALOG_REDIS_CACHING_USE_PARALLEL_QUERIES |
Before performing a release, update the CHANGELOG and whatsnew.rst with details of the release.
-
Add a new heading for the version being released.
-
If you are performing a major or minor release:
i. Add a Summary subsection with the highlights of the release. Any migration notes should also be included in this section. ii. Add a Changes subsections to list individual changes (
git log --oneline $PREVIOUS_RELEASE_TAG..HEADshould provide a good basis for the list). Further seperate this list into Version Updates, New Features, and Bugfixes. -
If you are performing a patch release, instead just list the changes, without any subsections. This should be pretty short, or else you probably shouldn't be doing a patch release.
-
Update build.properties and banner.txt with the version of the new release.
-
Push the updated files to master.
Stratus is released using Jenkins, via the stratus-release job. When run, this job will:
- Run all tests.
- Remove -SNAPSHOT from the project version
- Commit and Tag in git with v${version}.
- Increment the patch version by one, and add -SNAPSHOT back onto the version.
- Commit.
- Push commits and tag to the gsstratus/stratus repository.
- Trigger a new run of stratus-deploy-all against the released tag, which will create Docker images and push them to Docker Hub.
Jenkins configuration is managed in deploy/jenkins.
Requires:
- Git
- Maven
- Docker
- Commit access to https://github.com/gsstratus/stratus/releases
- A Docker Hub account, with access to https://docker.io/repository/gsstratus/stratus
- You must be logged into Docker Hub locally in docker
To run the release process locally, you can use the command:
mvn release:prepare --batch-mode -Dtag=$GIT_TAG -DreleaseVersion=$RELEASE_VERSION -DdevelopmentVersion=$DEVELOPMENT_VERSION
Where:
$GIT_TAG- The tag for the release, to be pushed to git. Usually of the formv1.2.0$RELEASE_VERSION- The maven version for the release, usualy of the form1.2.0$DEVELOPMENT_VERSION- The maven version to update master to, usually of the form1.2.1-SNAPSHOT.
(For more information on tagging and version guidlines, refer to tagging.md)
This will do everything the stratus-release job does except for building and deploying the docker images. To deploy
the release, checkout the newly created release tag, cd to the stratus-application submodule and follow the
instructions for deploying with docker.
After running the release job:
-
Verify the new git tag is listed at https://github.com/planetlabs/stratus/releases.
-
Still on GitHub, click
Draft a new release, selecting the tag you just pushed, and fill in details for this release (Only do this for final releases, not RCs). -
Verify the new docker tag is listed at https://docker.io/repository/gsstratus/stratus?tab=tags
You can test the release artifacts locally using single-host-deploy.sh in stratus:
-
Update
DOCKER_TAGto the tag you just pushed to docker.io, and ensure thatDOCKER_REPO=docker.io -
Run
single-host-deploy.sh. -
Navigate to http://localhost:8080/geoserver/web and verify the UI shows up.
-
Navigate to http://localhost:8080/geoserver/rest/manage/info and verify that the git commit id matches that of the release tag in git.
For integration testing, refer to the test/ directory.
This includes a number of integration and performance tests, and an upgrade test.
Stratus deployments can be found under deploy/.
This includes:
- Jenkins pipelines for CI.
- Scripts for standalone deployments for demos and testing.
- Kubernetes deployments, both manual and using helm.
- Terraform Deployments.
Any custom Docker images used by these deployments can be found in build/docker.
-
Ensure the methods in CommunityRestConfiguration are up to date with the current RestConfiguration class found in community GeoServer (note: community extends WebMvcConfigurationSupport and Stratus should extend WebMvcConfigurerAdapter)
-
Ensure all of the context XML files in the stratus-gwc are updated with any changes made in the corresponding GeoServer GWC context files. Note there are exceptions for context files that contain important custom configurations. These
files are: