Deployment & Production

Struts 7.4.0 ships with production-safe defaults, and the first thing to know is how little there is to switch off. The table lists the settings that distinguish a development run from a production run, with the 7.4.0 default (read from default.properties) and the value this page uses.

Source: Core Developer Guide — Development Mode

Source: Core Developer Guide — Reloading Configuration

The development-mode behaviour, the constants one by one and the load order of the files that set them are described in Configuration: struts.xml and Constants (see its section on reloading and development mode); the debugging side of devMode belongs to the debugging page of this section. What this page adds is everything around the WAR: where each request is handled, which headers it carries, which container features to switch on and how the WAR is packaged.

In production a request passes through more components than on a developer’s laptop, and the useful question for most problems is which of them answers. The figure shows the path of the Bookshelf WAR of this page.

The proxy and the connector are the only components that can see the original scheme and client address, which is why the valve at the start of the Tomcat pipeline restores them (see Behind a Reverse Proxy). The filter mapped to /* sees every request that reaches the web application and decides in two steps: if the URL starts with the static content path and Struts serves static content, it answers itself; otherwise it asks the action mapper for an action. A request with no action falls through to the next filter and, finally, to a servlet; that is how assets/app.css is served by Tomcat’s default servlet in the verification below, and also why an extensionless servlet URL needs the exclusion of Health Checks and Startup Failure.

All the examples on this page are files of one Maven project, g12prod, built from the Bookshelf of the Struts Getting Started page of this section (the Struts BOM, struts2-core, the Jakarta Servlet and Pages APIs as provided dependencies, Log4j 2). It adds a small servlet for health checks, static assets, two error pages and an action that always fails, so that every production behaviour can be requested.

The struts.xml is the heart of the production configuration. Each constant is explained in the sections that follow.

Source: Core Developer Guide — Constant Configuration

The web.xml adds Tomcat’s ExpiresFilter ahead of the Struts filter for the two static prefixes, the cookie settings of the session (Tomcat in Production) and error pages, so that a failing request never shows a container page. The filter order is the order of the <filter-mapping> elements.

Source: Core Developer Guide — web.xml

Source: Tomcat 11 — Expires Filter

The ExpiresFilter is a Tomcat class, so this web.xml runs on Tomcat only; on Jetty or GlassFish the same effect is obtained with a different filter or, better, at the proxy. The filter and the session settings are explained with their verification below. The full request matrix of this WAR is in Worked Example: Smoke-Testing the Bookshelf Production WAR.

Struts 7.4.0 starts in production mode unless told otherwise, and ?debug=xml is the quickest check of that. In the Bookshelf with struts.devMode set to true the request returns the value-stack dump, and with the default it returns the normal page (observed on Tomcat 11.0.26).

Source: Core Developer Guide — Development Mode

Teams that need different settings per environment have four mechanisms to choose from.

The Maven variant needs only a filtered resource and a profile.

mvn package then produced a struts.properties containing struts.devMode=false and mvn package -Pdev one containing struts.devMode=true; both WARs were deployed side by side and only the second answered ?debug=xml. Keep the filtered file tiny, because filtering replaces every ${...} in it, and filter only that file as the pom.xml above does. The init-params the Struts filter itself understands (config, configProviders and others) are listed in The Filter and Its Init-Params in web.xml. Secrets, such as database passwords, do not belong in any of these files; the Kubernetes and Docker pages of this site (Secrets, ConfigMaps) show how the container platform injects them.

Source: Maven Resources Plugin — Filtering

Source: Maven — Introduction to Build Profiles

Struts can serve static files itself. The Core Developer Guide describes the arrangement: the constant struts.ui.staticContentPath (default /static) names a path prefix, the StaticContentLoader (default DefaultStaticContentLoader) answers requests under it from the classpath, and the same path serves the files that the xhtml and css_xhtml themes need (s:head emits links to them). The Bookshelf shows the default arrangement first.

Struts adds Cache-Control: public and an Expires one day ahead, the browser-cache behaviour that struts.serve.static.browserCache=true stands for; the Retry-After header with the same date is sent too and means nothing for a 200. With struts.serve.static.browserCache=false the answer carries Cache-Control: no-cache, Pragma: no-cache and Expires: -1 instead, which is useful while the static files of a plugin change. Both forms are verified on 7.4.0.

Source: Core Developer Guide — Static Content, Default Content Loader

Source: Struts Javadoc — StaticContentLoader

The Performance Tuning page of the Core Developer Guide is a list of tips written for versions between 2.0 and 2.5, with newer entries added later. The table below goes through each tip and says what is true of 7.4.0; the sections after it show the measurements.

Source: Core Developer Guide — Performance Tuning

The Application Servers page of the Core Developer Guide is a list of products with a few links, written for the era of JRun, OC4J, Orion, Resin and SunOne; it also names JBoss 5, WebLogic, WebSphere, Glassfish 2.x and Wildfly 10.x. None of them is a target for Struts 7, which needs Servlet 6 (Jakarta EE 10 or newer). A Struts 7 WAR is an ordinary Jakarta Servlet 6 application and runs on any container that implements it. Three were run for this page.

Server-specific differences are small and are all in the container, not in Struts: the way static files get their content type, the default session cookie attributes, how a context path is chosen, the error page the container writes when Struts does not. Nothing in struts.xml changes. The configuration of the WAR for Jetty is a plugin entry in the pom.xml.

Source: Eclipse Jetty — Using the Jetty Maven Plugin

Source: Eclipse GlassFish Quick Start Guide — Deploying and Undeploying Applications

The Jetty plugin is a development and test tool, not a production server; a production Jetty is a Jetty base with the WAR in its webapps directory, described in the Jetty operations guide. The three-container table is a portability check and a reason to keep container-specific features (the ExpiresFilter, a Tomcat valve) behind a note in the deployment documentation of the project. The earlier getting-started pages of this section install the three servers and run the same WAR (Jetty 12.1 and GlassFish 8 as Alternatives, Deploying to Tomcat); a javax.servlet WAR needs migration first, as the pitfalls of that page explain.

Source: Core Developer Guide — Application Servers

Source: Eclipse Jetty Operations Guide — Java Server Pages

A production Struts application is nearly always behind a proxy or load balancer that terminates TLS. The container then sees plain HTTP from the proxy, and Struts, which builds absolute URLs from the request, would write http:// links. The s:url tag with forceAddSchemeHostAndPort shows the effect, and RemoteIpValve the fix; the proxy has to send X-Forwarded-Proto and the host.

The default internalProxies of the valve match loopback and private addresses, which is why the test from the same machine was trusted; in production the valve’s internalProxies must list exactly the proxies, so that clients cannot send their own X-Forwarded-For and become someone else’s address in the access log. The constants struts.url.http.port and struts.url.https.port exist for the port Struts writes into absolute URLs when the valve cannot be used (they were not run here). Other proxy duties are the proxy’s own: TLS, HTTP/2, the large-upload limit (the struts.multipart.maxSize family of the file upload limits must agree with the proxy’s body size limit), timeouts and buffering of long-running actions.

Source: Tomcat 11 — Remote IP Valve

Container platforms ask the application whether it is alive and ready. The cheapest probe is a servlet that answers a constant. It must bypass Struts (the previous section on Keeping Requests Away from Struts), and it must not touch the database, or the whole fleet is restarted when the database is slow.

Source: Jakarta Servlet 6.1 Javadoc — WebServlet

A servlet that always answers 200 is useful for exactly one reason that the bogus-cache run proved: when the Struts filter fails to initialise (a bad constant, a malformed struts.xml, a missing class), Tomcat does not start the context at all, and the health servlet, the static files and every action answer 404 together.

A readiness probe on /health therefore catches a configuration error (the pod never becomes ready and the rollout stops) without the application having to say so. The error itself, with the Caused by chain of the Struts exception, is in the container log; the first line to read after a failed deployment is the SEVERE message above, and the cause is the last Caused by line.

Source: Kubernetes — Configure Liveness, Readiness and Startup Probes

The Docker pages of this site cover images, layers, caches, non-root users and scanning; this page shows only what is specific to a Struts WAR. The Getting Started page of the JSP part has the verified multi-stage Dockerfile for a WAR on the official tomcat image (the image’s webapps directory is empty, a WAR named ROOT.war is served at /, and the image runs Tomcat as root): A Docker Image for the WAR. For the production WAR the Struts-specific parts are the build, the memory flags and the way to turn the constants into environment choices. The Docker daemon was not available for this page, so the following file was not built; it differs from the verified one only in the final stage.

Source: Docker Official Image — tomcat

Four rules carry over from the earlier sections. Use JAVA_OPTS (the JVM flags verified above were read back with jcmd); if the image ships a setenv.sh that assigns CATALINA_OPTS, an environment variable of the same name is overwritten (observed in this check with the scratch Tomcat, whose setenv.sh replaced the options the launcher exported). Struts constants are not read from system properties (verified) and no mechanism for environment variables is documented, so per-environment changes are either build variants (Production Constants and Environment-Specific Configuration), files mounted into the image (a struts.properties or an extra struts-*.xml read through the config init-param) or the container platform’s mechanism that the proxy and the application share. Send the logs to standard output (the log4j2.xml of Logging), so that docker logs shows them. And size the heap relative to the container memory with MaxRAMPercentage, because an -Xmx copied from a bare-metal server is wrong in a container with a 512 Mi limit.

The Docker pages cover the rest: Dockerfile Fundamentals, Java and Spring Boot Images, Image Best Practices and Security and Resources, Logging and Monitoring. For integration tests that start the WAR in a container, Testcontainers Fundamentals applies unchanged.

The Kubernetes pages of this site explain every object; the manifest below only shows what a Struts WAR adds to a standard Deployment: probes on the health servlet, JVM flags from the container memory and a memory limit that the heap setting can use. It was parsed as YAML but not applied to a cluster, because no cluster was available.

Source: Kubernetes — Configure Liveness, Readiness and Startup Probes

The probe path /health answers 200 only when the Struts filter started, as shown above, and the readiness probe’s five-second period lets a bad rollout stop early. The image name is a placeholder; nothing in it is a credential. A non-root user and a read-only root file system are good practice but need the temp, work and logs directories of Tomcat on writable volumes, and were not tried; start from Health Probes and Lifecycle, Resource Management, Deployment Strategies and ConfigMaps for each. A rolling update brings old and new versions up together, so session handling matters: sessions live in the pod that created them and are lost when it is replaced, unless the application keeps nothing important in the session or the container replicates sessions. The production Bookshelf keeps nothing in the session.

The Struts project maintains three sources of working code, and each has a catch that this page checked.

Source: Struts Examples — README

Source: Struts 7.4.0 — apps/README.md

Source: Struts — Maven Archetypes

The examples are the right place to see a feature in the smallest possible application; every topic page of this section names the module that matches it. Because the examples lag the release (7.3.0 against 7.4.0), read them for structure and take versions from the BOM of your own project. The showcase is the right place to see every tag and every theme in one application, and the better thing to run when comparing a tag’s behaviour with the Tag Developer Guide. The archetypes are the weak spot: they generate Struts 6.0.0 projects, an xmlns.jcp.org descriptor and an old DTD. A Struts 7 project is better started from the BOM and the filter as in Getting Started with Struts, with the struts-6.0.dtd DOCTYPE that every example of this section uses (why 6.0).

Source: Struts — Getting Started tutorials

The checklist collects the page into a table to read before a deployment. Rows that point to other pages are the ones that need a decision rather than a constant.

The checklist was applied to the g12prod WAR and a single script of curl calls was run against it on the private Tomcat instance (context path /g12prod). The session id of the one cookie shown is replaced by a placeholder.

Source: Tomcat 11 — Error Report Valve

Source: Tomcat 11 — Expires Filter

Read the transcript as the evidence for each row of the checklist. The books response carries the Struts security headers of the default stack and has no Set-Cookie. The static files carry the seven-day lifetime. health and assets/app.css bypass the Struts filter. A request for a missing page and for a failing action produce the application’s own HTML, with no server version, no stack trace and no Struts message, and the stack trace is in the log. A request with request_locale creates the only session, with all three cookie flags. And ?debug=xml is an ordinary page. The same WAR answered 200 on Jetty 12.1.14 and GlassFish 8.0.5 apart from the Tomcat-only ExpiresFilter, which Jetty and GlassFish would need equivalents for.

The behaviour changes that matter to a production move from Struts 6 to 7 (Jakarta namespace, struts.mapper.alwaysSelectFullNamespace true, the allowlist and @StrutsParameter requirements) are in the section’s migration page; the Tomcat side is that a Tomcat 11 webapps directory accepts only Jakarta WARs and answers 404 for a javax one without a message (see the pitfalls of the Getting Started page).

Source: Core Developer Guide — Performance Tuning

The books on Struts and on web deployment were written for Struts 2.x on Tomcat 5 to 8, and four assumptions are out of date.

Several statements of the official pages do not match 7.4.0. The first three are measured on the Bookshelf, the rest were read from the pages and the jar.

A Struts 7.4 WAR is production-ready by default and the work is in what surrounds it. Keep devMode and the reload switches off and check with ?debug=xml; let the container or a proxy serve static files (struts.serve.static=false, the jar’s files extracted, ExpiresFilter or proxy caching) and send servlets and health endpoints around Struts with struts.action.excludePattern; leave the OGNL caches at wtlfu and give FreeMarker a long update delay; keep logging at warn for Struts and FreeMarker; create sessions only on purpose and do not trade the security-header interceptors for speed; harden Tomcat with a Host-level ErrorReportValve, error pages, RemoteIpValve and cookie flags; deploy the same WAR to Tomcat 11, Jetty 12.1 or GlassFish 8; and expose a /health servlet for probes, remembering that a failed Struts filter takes the whole context down with a 404. Docker and Kubernetes add a start-up command, probes and memory limits around that WAR and are covered by their own pages. Take learning code from struts-examples and the showcase, versions from the BOM, and never from a 6.0.0 archetype.