Tomcat Integration Thing
Tomcat Integration Thing gives one Banalytics Agent a managed local home for approved Java web applications. Use it when a site needs a focused interface, guided workflow, or utility close to its equipment and operational data, without introducing a separate unmanaged web server.
A local web experience with a named site role
A managed WAR is useful when it has a clear local purpose: helping a technician commission one infrastructure object, giving a shift team a tailored view of one Agent, or delivering a selected operational event to the people who need it. The container is the managed boundary; the deployed application remains responsible for its own workflow, users, and data.
This pattern fits industrial sites, distributed organisations, small businesses, and advanced private installations. It is not a general-purpose hosting platform, a replacement for a safety controller, or an implicit way to expose every Agent capability to a browser.
Industrial commissioning wizard
A packaging line, pump station, laboratory cell, or energy cabinet can receive a purpose-built wizard that checks local prerequisites and guides an authorised technician through the approved sequence. The wizard supports the process; it does not replace PLC, safety, or quality-system authority.
Targeted interface for one Agent
A warehouse dock, retail branch, building plant room, or field installation can have a small portal that presents the controls, evidence, and status relevant to that location.
Object-specific configuration
A custom application can turn repeatable infrastructure setup into a guided workflow: select supported equipment, collect approved values, validate prerequisites, and hand the result to the designated operating procedure.
Real-time operational handoff
A local site application can receive a selected event and route it to maintenance, security, facilities, reception, or customer service. The same pattern gives a small business or household a focused local notification or service page.
Interface service for Agent components
A reviewed web application can implement a defined REST, SOAP, or other integration contract and translate each permitted request into interaction with selected Agent components. This gives external systems a stable, purpose-built interface without exposing the Agent's full internal surface.
Approved utility software
Use a bounded local utility for diagnostics, label generation, maintenance checklists, evidence review, or a specialist device workflow when it needs a browser interface and explicit lifecycle beside the Agent.
One managed container for approved applications
The Thing starts one separate embedded Apache Tomcat 9 container inside the Agent JVM. It does not reuse the Tomcat that serves the Agent's Spring Boot web layer. Each container has its own bind address, HTTP and HTTPS connectors, working directory, request limits, in-memory access log, and statistics.
Separate Tomcat Web Application Thing instances deploy one WAR each into this container. The Tomcat runtime is private to the module and isolated from the Agent's broad dependency set.
Shared endpoint
Applications share selected HTTP and HTTPS listeners while keeping distinct context paths.
Transport boundary
HTTPS uses a JKS keystore, an optional key alias, and optional client certificates.
Local visibility
Access observations and cumulative statistics make active contexts visible to operators.
Create a stable container boundary
Choose the network exposure
Use 127.0.0.1 when a local reverse proxy or service is the only client. Use a specific LAN address, or 0.0.0.0, only when direct network access is deliberate and protected.
Reserve connector ports
Enable HTTP, HTTPS, or both. Every enabled port must be free, and HTTP and HTTPS cannot use the same port.
Prepare a dedicated workspace
Select an existing writable directory for Tomcat work, temporary files, and generated deployments. Keep original release WARs outside it.
Add applications after startup
Create one Web Application Thing for each approved WAR and give every application a unique context path.
Protect the listener and the deployed code
Binding to all interfaces makes every application in the container reachable on that connector. Restrict exposure with an explicit address, host firewall, network controls, or a reverse proxy. The container provides transport security; application authentication, authorisation, sessions, input validation, and data access remain responsibilities of the WAR.
BoxEngine in its servlet context. Deploy reviewed, owned artifacts only.Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
Title | Yes | Display name for the Tomcat container. | Empty |
Bind address | Yes | Address used by enabled connectors. Use a loopback or specific address to limit exposure. | 0.0.0.0 |
HTTP connector / port | Yes | Enables HTTP and selects its port; range 1-65535. | Enabled / 8081 |
HTTPS connector / port | Yes | Enables HTTPS and selects its port; range 1-65535. | Disabled / 8443 |
Keystore / key alias / password | Conditional | JKS server key material for HTTPS. Password supports Secret Manager; an empty alias lets Tomcat select a usable key. | None |
Client certificates | Conditional | NONE, WANT, or NEED. A truststore is required for WANT or NEED. | NONE |
Max request threads | Yes | Maximum request-processing threads per connector; range 1-1000. | 50 |
Connection timeout | Yes | Time allowed for incomplete request data; range 1000-600000 ms. | 20000 ms |
Working directory | Yes | Existing writable directory for Tomcat work and expanded application files. | None |
Access log capacity | Yes | Configured recent in-memory request records; range 0-10000. | 500 |
Statistics event interval | Yes | Period for TomcatContainerStatsEvent; 0 disables periodic events. | 60 sec |
JSP deployment warning | Yes | Warns when a WAR contains JSP/JSPX source files that should normally be precompiled. | Enabled |
Operate the container as part of the site service
Container statistics
Read requests, errors, traffic, response times, active requests, uptime, and per-context counters. Periodic samples are published as TomcatContainerStatsEvent.
Recent access observations
Read the bounded in-memory log by context path and sequence number for current diagnostics. It is not an audit trail.
Planned restart scope
Changing connectors, TLS, threads, timeout, or workspace restarts the container and temporarily affects all hosted applications.