SHOGun is an application framework written in Java for building scaleable web application backends in the context of geospatial data infrastructures. It can be used directly without any specific customizations or highly customized to meet the demands of flexible project requirements.
SHOGun…
- …is written in Java and supports Java >= 21.
- …is based on top of Spring / Spring Boot.
- …provides a set of configuration entities to manage the contents of a geospatial data infrastructure (e.g. layers, applications, users or groups).
- …provides (secured) web interfaces (REST & GraphQL) for accessing and manipulating these entities (e.g. for creating an application configuration).
- …separates its functionalities into isolated microservices (e.g. for proxying OGC requests) and is highly scalable.
For the development of SHOGun the following tools are required locally:
- maven >= 3.9
- Java 21
- docker and docker compose
- IntelliJ (recommended)
- IntelliJ Lombok plugin
To set up a local development setup, please proceed as follows:
-
Checkout this repository:
git clone git@github.com:terrestris/shogun.git
-
Checkout the
shogun-docker
repository:git clone git@github.com:terrestris/shogun-docker.git
-
Create a new project in IntelliJ by importing the first module:
File
->New
->Project from Existing Sources…
- Navigate to the checkout of
shogun
- Select the Project Object Model file (
pom.xml
) ofshogun
-
Optional: You may also want to import the
shogun-docker
project. If so, import the folder as a module:File
->New
->Module from Existing Sources…
- Navigate to checkout of
shogun-docker
and choose the directory
-
If not already done, the annotation processing of the Lombok plugin must be enabled. Check the settings for
Lombok
(Enable Lombok plugin for this project) andAnnotation Processors
(Enable annotation processing). -
Set up the shogun-docker requirements as described in here.
-
Startup the containers (in the
shogun-docker
checkout directory):docker compose up
-
The application is now available at https://localhost/.
If you already have a local development setup, just proceed as follows:
-
Startup the containers (in the
shogun-docker
checkout directory):docker compose up
-
The application is now available at https://localhost/.
Install a new version of SHOGun to your local maven repository with
mvn clean install
or
maven clean install -DskipTests -Djib.skip=true
To apply any changes made, a restart of the application is required. A restart can easily be accomplished by restarting the appropriate container, e.g.:
docker restart shogun-boot
To create a remote debugger, a new run configuration in IntelliJ has to be created:
- Open
Edit configurations
in theRun
menu. - Add a new
Remote JVM debug
configuration and enter the following properties:- Name:
shogun-boot remote debugger
- Host:
localhost
- Port:
4711
(may be adjusted to the given module/service) - Use module classpath:
shogun-boot
(or any other module)
- Name:
To use REST API of GeoServer interceptor it's necessary to create a role
interceptor_admin
in Keycloak. Users having this role are allowed to use them.
If you want to create a report with detailed information about the projects dependencies or similar, you can use this command:
mvn site -Preporting
Just have a look at /target/site/index.html
afterwards.
To get an access token programmatically the following curl can be used (adjust <EXTERNAL_KEYCLOAK_HOST>
beforehand):
curl \
-v \
-k \
-X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=password' \
-d 'client_id=shogun-client' \
-d 'username=shogun' \
-d 'password=shogun' \
'https://<EXTERNAL_KEYCLOAK_HOST>/auth/realms/SHOGun/protocol/openid-connect/token' | jq '.access_token'
The usage of jq
is optional and can be removed if not needed or jq
is not available.
Spring Boot Actuator
is enabled by default and is available via the actuator/
endpoints.
The following list demonstrates some use cases:
-
List current properties:
https://localhost/actuator/configprops
-
List current status of flyway migrations:
https://localhost/actuator/flyway
-
List current health information:
https://localhost/actuator/health
-
List build and git information:
https://localhost/actuator/info
-
List current log levels:
https://localhost/actuator/loggers
-
List current log level of a specific module:
https://localhost/actuator/loggers/de.terrestris
-
Set log level for a specific module to the desired level (e.g.
DEBUG
forde.terrestris
):curl \ -v \ -X POST \ -H 'Authorization: Bearer <TOKEN>' \ -H 'Content-Type: application/json' \ -d '{"configuredLevel": "DEBUG"}' \ 'https://localhost/actuator/loggers/de.terrestris'
-
List all available endpoint mappings:
https://localhost/actuator/mappings
Note: All endpoints are accessible by users with the ADMIN
role only.
- To trigger a release, manually run the
Publish
github action
SHOGun supports auditing of entities, powered by Hibernate Envers.
Auditing is enabled by default and can be disabled by setting spring.jpa.properties.hibernate.integration.envers
to false
.
If envers is enabled mid-way and there is already data this can result in errors when querying audit data. To fix this, a revision with revision type 0
(created) has to be manually inserted for each existing entity into the respective audit table.
See https://discourse.hibernate.org/t/safe-envers-queries-when-the-audit-history-is-incomplete/771.