Skip to content

Commit 2c35603

Browse files
offtherailzofftherailz
committed
Update developer guide for Spring 7 upgrade (#12560)
1 parent ce9f22a commit 2c35603

5 files changed

Lines changed: 144 additions & 11 deletions

File tree

‎docs/developer-guide/advanced-project-customization.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,12 @@ Find the entry for `cargo-maven3-plugin` and add the `systemProperties` tag with
3232
<artifactId>cargo-maven3-plugin</artifactId>
3333
<configuration>
3434
<container>
35-
<containerId>tomcat8x</containerId>
35+
<containerId>tomcat10x</containerId>
3636
<systemProperties>
3737
<datadir.location>[local_path_to_your_datadir]/datadir/[customInstallationFolder]</datadir.location>
3838
</systemProperties>
3939
<zipUrlInstaller>
40-
<url>https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/8.5.69/tomcat-8.5.69.zip</url>
40+
<url>https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/10.1.55/tomcat-10.1.55.zip</url>
4141
</zipUrlInstaller>
4242
</container>
4343
<configuration>

‎docs/developer-guide/configuration-files.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ java -Ddatadir.location=/path/to/data-dir -jar mapstore.war
139139

140140
In servlet containers like Tomcat, you can set Java system properties in the `setenv.sh` file (for Unix-based systems) or `setenv.bat` file (for Windows systems) located in the `bin` directory of the Tomcat installation.
141141

142-
If you are using Tomcat as a service, you can set Java system properties in the service configuration file (for instance `/etc/default/tomcat9` in Ubuntu 20.04 ).
142+
If you are using Tomcat as a service, you can set Java system properties in the service configuration file (for instance `/etc/default/tomcat10` in Ubuntu).
143143

144144
### `datadir.location`
145145

‎docs/developer-guide/database-setup.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ MapStore has a file called `geostore-datasource-ovr.properties`. This file is on
2121
For production deployments, consider using the [externalized configuration](externalized-configuration.md) (`-Ddatadir.location=`) instead. It provides a single data directory that centralizes all MapStore configuration files (database, proxy, JSON configs, etc.) and persists across updates. The `geostore-datasource-ovr.properties` file can simply be placed inside that directory.
2222

2323
For instance using tomcat on linux you will have to do something like this to add the environment variable to the JAVA_OPTS
24-
> where to add your JAVA_OPTS depends on your operating system. For instance the file could be `/etc/default/tomcat8`, or similar, in linux debian
24+
> where to add your JAVA_OPTS depends on your operating system. For instance the file could be `/etc/default/tomcat10`, or similar, in linux debian
2525
2626
```properties
2727
# here the path to the ovr file

‎docs/developer-guide/mapstore-migration-guide.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,139 @@ This is a list of things to check if you want to update from a previous version
2020
- Optionally check also accessory files like `.eslinrc`, if you want to keep aligned with lint standards.
2121
- Follow the instructions below, in order, from your version to the one you want to update to.
2222

23+
## Migration from 2026.02.00 to 2026.03.00
24+
25+
### Spring 7 / Jakarta EE 10 upgrade
26+
27+
MapStore has been upgraded to Spring Framework 7 and Spring Security 7, moving from the Java EE (`javax.*`) to the Jakarta EE 10 (`jakarta.*`) platform. This is a **breaking change** for the deployment environment and for MapStore projects.
28+
29+
#### New deployment requirements
30+
31+
- **Java 17** is now the minimum supported version (Java 8/11 are no longer supported). The CI still tests on Java 17 and 21.
32+
- **Tomcat 10.1** (Jakarta Servlet API 6.0) is the new reference servlet container. The binary distribution ships Tomcat 11. **Tomcat 9 or older cannot run this version of MapStore**, since they are based on the `javax.*` servlet API.
33+
34+
#### Updating a MapStore project
35+
36+
The following changes must be applied to your project (see the updated [project templates](https://github.com/geosolutions-it/MapStore2/tree/master/project/standard/templates) for reference):
37+
38+
**`pom.xml` properties**: update the dependency versions:
39+
40+
```diff
41+
- <tomcat.version>9.0.116</tomcat.version>
42+
- <jackson.version>2.16.1</jackson.version>
43+
+ <tomcat.version>10.1.55</tomcat.version>
44+
+ <jackson.version>2.19.4</jackson.version>
45+
<!-- Spring Framework & Security (aligned) -->
46+
- <spring.version>5.3.39</spring.version>
47+
- <spring.security.version>5.7.13</spring.security.version>
48+
+ <spring.version>7.0.8</spring.version>
49+
+ <spring.security.version>7.1.0</spring.security.version>
50+
- <commons-pool.version>1.5.4</commons-pool.version>
51+
- <ehcache-web.version>2.0.4</ehcache-web.version>
52+
- <httpclient.version>4.5.13</httpclient.version>
53+
- <javax.servlet-api.version>3.0.1</javax.servlet-api.version>
54+
- <jaxws-api.version>2.3.1</jaxws-api.version>
55+
+ <jakarta.servlet-api.version>6.0.0</jakarta.servlet-api.version>
56+
+ <jaxws-api.version>4.0.3</jaxws-api.version>
57+
- <cargo.version>1.10.2</cargo.version>
58+
+ <cargo.version>1.10.27</cargo.version>
59+
<!-- MapStore‑specific -->
60+
- <mapstore-services.version>1.10-SNAPSHOT</mapstore-services.version>
61+
- <geostore-webapp.version>2.6-SNAPSHOT</geostore-webapp.version>
62+
- <http_proxy.version>1.6-SNAPSHOT</http_proxy.version>
63+
- <print-lib.version>2.3.5</print-lib.version>
64+
+ <mapstore-services.version>1.12-SNAPSHOT</mapstore-services.version>
65+
+ <geostore-webapp.version>2.7-SNAPSHOT</geostore-webapp.version>
66+
+ <http_proxy.version>1.7-SNAPSHOT</http_proxy.version>
67+
+ <print-lib.version>2.5-SNAPSHOT</print-lib.version>
68+
```
69+
70+
**`web/pom.xml` dependencies**: replace the `javax` artifacts with their `jakarta` equivalents and remove the dependencies that are not used anymore (`net.sf.ehcache:ehcache-web`, `commons-pool:commons-pool`):
71+
72+
```diff
73+
<dependency>
74+
- <groupId>javax.servlet</groupId>
75+
- <artifactId>javax.servlet-api</artifactId>
76+
- <version>${javax.servlet-api.version}</version>
77+
+ <groupId>jakarta.servlet</groupId>
78+
+ <artifactId>jakarta.servlet-api</artifactId>
79+
+ <version>${jakarta.servlet-api.version}</version>
80+
</dependency>
81+
- <!-- gzip compression filter -->
82+
- <dependency>
83+
- <groupId>net.sf.ehcache</groupId>
84+
- <artifactId>ehcache-web</artifactId>
85+
- <version>${ehcache-web.version}</version>
86+
- </dependency>
87+
- <dependency>
88+
- <groupId>commons-pool</groupId>
89+
- <artifactId>commons-pool</artifactId>
90+
- </dependency>
91+
<dependency>
92+
- <groupId>javax.xml.ws</groupId>
93+
- <artifactId>jaxws-api</artifactId>
94+
+ <groupId>jakarta.xml.ws</groupId>
95+
+ <artifactId>jakarta.xml.ws-api</artifactId>
96+
<version>${jaxws-api.version}</version>
97+
</dependency>
98+
```
99+
100+
**`web/pom.xml` `printing` profile**: if your project defines the `printing` profile, the same `javax` artifacts appear again in its `<dependencyManagement>` section. Replace them with the `jakarta` equivalents as above, and remove the `httpclient`, `ehcache-web` and `commons-pool` entries: their version properties no longer exist in the root `pom.xml`, so a build with `-Pprinting` would fail on the unresolved placeholders.
101+
102+
**`web/src/main/webapp/WEB-INF/web.xml`**: update the schema declaration to Jakarta EE 10 and remove the GZip `CompressionFilter`, together with its three `filter-mapping` entries (the filter class comes from the removed `ehcache-web` library, which is not available for the `jakarta.*` namespace):
103+
104+
```diff
105+
-<web-app id="WebApp_ID" version="2.4"
106+
+<web-app id="WebApp_ID" version="6.0"
107+
xmlns:javaee="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
108+
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
109+
+ xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd">
110+
```
111+
112+
!!! note
113+
The removed `CompressionFilter` used to gzip `*.js`, `*.css` and `*.html` responses out of the box. Compression has to be configured in the deployment environment instead:
114+
115+
- **Tomcat exposed directly**: enable compression on the connector in `conf/server.xml`:
116+
117+
```xml
118+
<Connector port="8080" ... compression="on"
119+
compressibleMimeType="text/html,text/css,text/plain,application/javascript,application/json,application/xml,image/svg+xml"/>
120+
```
121+
122+
- **Behind a reverse proxy (recommended)**: enable gzip (or brotli) in the proxy; e.g. for nginx:
123+
124+
```nginx
125+
gzip on;
126+
gzip_vary on;
127+
gzip_types text/css text/plain application/javascript application/json application/xml image/svg+xml;
128+
```
129+
130+
- **Docker composition**: nothing to do, compression is already enabled in the bundled nginx configuration (`docker/mapstore.conf`).
131+
132+
Without it MapStore still works, but the JavaScript bundles are quite big and the first load becomes noticeably slower.
133+
134+
**`WEB-INF/*-servlet.xml`** (`configs-servlet.xml`, `extensions-servlet.xml`, `loadAssets-servlet.xml`): Spring Security 7 replaced the `global-method-security` element:
135+
136+
```diff
137+
- <security:global-method-security secured-annotations="enabled" />
138+
+ <security:method-security secured-enabled="true"/>
139+
```
140+
141+
**Security configuration overrides**: if your project overrides `geostore-spring-security.xml` (e.g. for [LDAP](integrations/users/ldap.md) or database authentication), the file must be aligned with the new Spring Security 7 syntax. Copy the updated reference files from the MapStore repository (`web/src/config/db/geostore-spring-security-db.xml`, `web/src/config/ldap/geostore-spring-security-ldap.xml`) and re-apply your customizations on top of them.
142+
143+
**Cargo (local test container)**: update the container id and add the logging configuration file:
144+
145+
```diff
146+
- <containerId>tomcat9x</containerId>
147+
+ <containerId>tomcat10x</containerId>
148+
```
149+
150+
Copy the `logging.properties` file from the MapStore repository (`product/cargo/logging.properties`) into the `web/cargo/` folder of your project and reference it in `cargo.jvmargs` with `-Djava.util.logging.config.file=${project.basedir}/cargo/logging.properties`. Note that `${project.basedir}` points to the `web` module, where the Cargo plugin runs. New projects created from the templates already include this file.
151+
152+
**Custom Java code**: any custom backend code must be migrated from the `javax.*` to the `jakarta.*` namespace (e.g. `javax.servlet.http.HttpServletRequest` → `jakarta.servlet.http.HttpServletRequest`) and compiled with source/target 17.
153+
154+
**CI/CD**: update your build infrastructure to use JDK 17 as the build JDK.
155+
23156
## Migration from 2026.01.02 to 2026.02.00
24157

25158
### Custom map resolutions moved from `new.json` to the `CRSSelector` plugin

‎docs/developer-guide/requirements.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@ In this section you can have a glance of the minimum and recommended versions of
66

77
You can download a java web container like *Apache Tomcat* from and *Java JRE*
88

9-
| Tool | Link | Minimum | Recommended | Maximum |
10-
|--------|----------------------------------------------------|-----------------|-------------|---------------|
11-
| Java | [link](https://jdk.java.net/archive/) | 11<sup>1</sup> | 17 | 21 |
12-
| Tomcat | [link](https://tomcat.apache.org/download-90.cgi) | 8.5 | 9 | 9<sup>2</sup> |
9+
| Tool | Link | Minimum | Recommended | Maximum |
10+
|--------|----------------------------------------------------|------------------|-------------|---------|
11+
| Java | [link](https://jdk.java.net/archive/) | 17<sup>1</sup> | 17 | 21 |
12+
| Tomcat | [link](https://tomcat.apache.org/download-10.cgi) | 10.1<sup>2</sup> | 10.1 | 11 |
1313

1414
## Debug / Build
1515

@@ -19,15 +19,15 @@ These tools needs to be installed (other than **Java** in versions above above):
1919
|-----------------------|------------------------------------------------------------|---------|-------------|-----------------|
2020
| npm | [link](https://www.npmjs.com/get-npm) | 8 | 10 | |
2121
| NodeJS | [link](https://nodejs.org/en/) | 20 | 20 | 24<sup>3</sup> |
22-
| Java (JDK) | [link](https://jdk.java.net/archive/) | 11 | 17 | 21 |
22+
| Java (JDK) | [link](https://jdk.java.net/archive/) | 17 | 17 | 21 |
2323
| Maven | [link](https://maven.apache.org/download.cgi) | 3.1.0 | 3.6 | |
2424
| python<sup>4</sup> | [link](https://www.python.org/downloads/) | 2.7.9 | 3.7 | |
2525

2626
!!! notes
2727
Here some notes about some requirements and reasons for max version indicated, for future improvements and maintenance :
2828

29-
- <sup>1</sup> Java 8 is the minimum version required for running MapStore, but it is not compatible in case you want to use the print module. In this case, you need to use Java 11.
30-
- <sup>2</sup> Running with Tomcat 10 causes this issue [#7524](https://github.com/geosolutions-it/MapStore2/issues/7524).
29+
- <sup>1</sup> Java 17 is the minimum version required since the upgrade to Spring 7 (see the [migration guidelines](mapstore-migration-guide.md)). Previous versions of MapStore could run on Java 8/11.
30+
- <sup>2</sup> Since the upgrade to Spring 7 / Jakarta EE 10, MapStore requires a servlet container supporting the Jakarta Servlet API 6.0 (`jakarta.*` namespace): Tomcat 10.1 is the reference target, and the binary distribution ships Tomcat 11. Tomcat 9 or older (based on the `javax.*` namespace) is **not** supported anymore.
3131
- <sup>3</sup> Latest version tested.
3232
- <sup>4</sup> Python is only needed for building documentation.
3333

0 commit comments

Comments
 (0)