Regalamiunsorriso/LOCAL_DEV_JSP_DOCKER_ANALYSIS.md

Local JSP Docker Analysis

Goal

Turn the public www site plus the legacy rus admin menu/runtime into a Docker-based local development environment with:

• full JSP and servlet execution
• enough filesystem layout to satisfy docbase-based file lookups
• a mocked MySQL-compatible database that lets the app boot and the admin menu render
• a workflow that supports editing JSPs and restarting quickly during local development

This document is an implementation analysis, not a finished deployment recipe.

What The Live System Actually Looks Like

Read-only checks on 83.149.164.4 show the production site is not running from a packaged WAR. It is running from an exploded Tomcat webapp:

• OS: FreeBSD 14.2
• Java: OpenJDK 11.0.25
• Tomcat: 9.0.102
• catalina.home and catalina.base: /usr/local/apache-tomcat-9.0
• Tomcat server.xml contains a dedicated host for www.regalamiunsorriso.it
• The live context for / points at /home/sites/regalamiunsorriso/www/
• Tomcat AJP is enabled on port 8009

Important nuance:

• /home/sites/regalamiunsorriso/www/WEB-INF is a real directory
• /home/sites/regalamiunsorriso/rus/WEB-INF is also a real directory
• the live www/WEB-INF/lib is much larger than rus/WEB-INF/lib
• the live rus/WEB-INF/classes contains the DB property files
• the live www/WEB-INF/classes appears minimal
• Tomcat server.xml maps the live public host only to /home/sites/regalamiunsorriso/www/
• no live Tomcat Context for /home/sites/regalamiunsorriso/rus/ was visible in server.xml

That means the runtime is split across two legacy trees, but the currently mapped live webapp is www. For local Docker work, assuming www alone is sufficient would still be unsafe, because the older rus tree remains the clearest source of legacy admin code, schema SQL, and bootstrap logic.

What The Repo Shows

www

The www tree is the public web root and already includes:

• JSP pages
• WEB-INF/web.xml
• taglibs such as acxent.tld, pg.tld, news.tld, cc.tld
• a large WEB-INF/lib with modernized it.acxent.* jars
• an admin/menu tree with JSP admin UI

Evidence of the rename/migration is strong in www:

• JSPs import it.acxent.*
• www/WEB-INF/web.xml maps servlets under it.acxent.*
• www/WEB-INF/lib contains acxent-core, acxent-common, acxent-face, and related jars

The current www/WEB-INF/web.xml shows:

• servlet/filter mappings for JSP and rewritten .html URLs
• admin menu servlet mappings under /admin/menu/*
• startup servlets that update DB structures on boot
• DB config pointing to MySQL-compatible settings
• direct dependence on application parameters and filesystem-backed assets

rus

The rus tree contains the older admin/runtime stack and still matters for local development:

• rus/WEB-INF/web.xml is another full Java webapp descriptor
• rus/admin/menu contains the older admin dashboard JSPs
• rus/WEB-INF/lib/*_src contains source code for key servlet, DB, and parameter logic
• rus/admin/_alterTable/pg2rus.sql contains a large schema for the application domain, including GARA, TIPO_GARA, PUNTO_FOTO, ACCESS, USER_ACCESS, and LOG_FOTO
• rus/WEB-INF/classes/dbcomuni.properties sets USE_PARM_HT=true

Evidence that rus is the older lineage is equally strong:

• rus/admin/menu JSPs import com.ablia.*
• rus/WEB-INF/web.xml maps servlets under com.ablia.*
• rus/WEB-INF/lib contains ablia.jar, abliaDbCom.jar, and multiple *_src trees
• rus/WEB-INF/lib/decomp.bat suggests this tree has already been treated as a reverse-engineering or recovery surface rather than a clean source distribution

This is also where the clearest bootstrap logic lives. Parm.java seeds defaults for some records such as:

• SINGLE_SIGN_ON=false
• LOGO_MENU=Titolo Applicazione
• PATH_TMP=_tmp/
• MAIL_MSG_PATH_MAILER=mailMessage/
• REWRITE_URL_FILE_PATH=/admin/_alterTable/

That helps, but it does not remove the need for a real schema or baseline user/access data.

Migration Interpretation

The evidence supports this interpretation of the ablia to acxent transition:

• the active public runtime has moved to the acxent namespace and libraries under www
• the rus tree is still valuable, but it is a legacy ablia runtime/reference tree rather than the clean current implementation
• the live host mapping reinforces that shift, because Tomcat serves www and does not visibly publish rus as its own live host context

That means the safest handling is:

• keep the current rus tree as a legacy backup/reference
• do not treat the existing rus tree as the current canonical codebase
• if you want a fresh, updated rus-equivalent admin/runtime tree, obtain it separately and preserve it as a new artifact rather than overwriting this legacy one
• if the fresh artifact is delivered only as jars or compiled classes, decompiling those classes into a browsable source mirror is reasonable for local analysis and maintenance

What the current evidence does not prove:

• that such a fresh downloadable rus tree is already present in this repo
• that the live server still executes rus directly for public requests

So the evidence supports the preservation and decompilation strategy, but not a claim that this repository already contains the fresh replacement.

The Admin Boundary

There are effectively two admin surfaces in the repo:

• www/admin/menu, using the newer it.acxent.* stack
• rus/admin/menu, using the older com.ablia.* stack

The www admin menu already contains compatibility links such as /admin/pg_RUS/Gara, which is a strong sign that the public app has been carrying forward legacy admin functionality instead of replacing it cleanly.

For Docker, that means there are two viable targets:

1. boot only the www webapp and bring over enough rus data/assets to satisfy the legacy admin links
2. boot both www and rus as separate Tomcat contexts and keep the boundary explicit

The second option is safer for analysis and migration because it matches the repository reality better.

What “Full JSP Support” Actually Requires

To satisfy the request, a local container must support more than static JSP rendering.

It needs:

• Tomcat 9 with JSP compilation enabled
• Java 11 first, because that is what production is currently running
• exploded webapp deployment so JSP edits are visible without rebuilding a WAR each time
• both taglib trees and both WEB-INF/lib trees available at runtime
• a writable temp/work area for Tomcat compiled JSPs
• a writable app docbase for uploads, generated files, CSV imports, image lookups, and mail templates
• a MySQL-compatible database reachable by the app at startup

It also needs to tolerate the app's legacy assumptions:

• path concatenation against DOCBASE
• direct filesystem existence checks inside taglibs and servlets
• startup DB mutation via InitUpdateDbSvlt
• servlet code that chooses JSP pages dynamically based on ACCESS, request params, and file existence

Data Strategy

The application does not just query a few content tables. It uses the database as runtime configuration.

For this codebase, the most practical local-development strategy is not to handcraft mock rows first. It is to start from a dump of the real production-shaped database and trim or sanitize later if needed.

This is now directly supported by the local workspace state. The following dumps already exist under db/:

• dump-pg-202604211927.sql
• dump-pg_log-202604211930.sql
• dump-mysql-202604211926.sql
• dump-performance_schema-202604211926.sql
• dump-sys-202604211930.sql

For local development, dump-pg-202604211927.sql should be treated as the primary seed source.

At minimum, local boot for useful development will require:

• PARM
• USERS
• USER_PROFILE
• ACCESS
• USER_ACCESS
• TABLE_DESC
• photo/event tables such as GARA, TIPO_GARA, PUNTO_FOTO, and likely additional related tables referenced by the servlets

The admin menu depends on both authentication and metadata-driven routing. A DB with only schema and no seed data will not be enough.

There are some useful seed hints already in the repo:

• old user/profile bootstrap SQL under www/admin/_alterTable/_old
• schema SQL under rus/admin/_alterTable/pg2rus.sql
• parameter defaults embedded in rus/WEB-INF/lib/ablia_src/com/ablia/common/Parm.java

What is missing from the repo is not raw data, but a curated minimal subset and a documented import procedure for local use.

If you use the real dump as the starting point, the first local milestone becomes:

• import the real pg dump locally
• override the environment-sensitive values after import, especially PARM.DOCBASE and any mailer or file-path settings
• document one admin login and one public sample flow that are known to work against the imported snapshot

This is materially easier and more faithful than trying to synthesize a coherent mock dataset from schema alone.

Recommended Docker Shape

Recommendation

Build a multi-service local stack with one shared source volume and one MySQL service.

Suggested services:

• tomcat-www: Tomcat 9 serving www as the ROOT webapp
• tomcat-rus: Tomcat 9 serving rus at /rus or /admin-rus
• mysql: MySQL 8 or MariaDB 10.11 used only for local development

Optional but useful:

• nginx: reverse proxy that exposes one friendly local hostname and routes / to tomcat-www and /rus to tomcat-rus

Why this is the best first step:

• it preserves both legacy runtimes instead of prematurely merging them
• it allows JSP edits against exploded directories
• it gives you a clean place to prove which admin flows still belong to rus
• it minimizes risky assumptions about the live cross-tree wiring

Alternative

Run only one Tomcat container with www as ROOT and manually overlay selected rus assets into it.

This is possible, but I would not start there because:

• it bakes in guesses about a split runtime that is already unclear
• it makes failures look like classpath bugs even when the problem is missing legacy assets
• it is harder to reason about during early local bring-up

Filesystem Layout Needed Inside Docker

A working local setup should not rely only on the web roots. It should create an application docbase volume as well.

Suggested mounted paths:

• /workspace/www -> repo www
• /workspace/rus -> repo rus
• /data/docbase -> local writable application docbase
• /data/docbase/_tmp -> temp uploads and generated files
• /data/docbase/admin/csv -> CSV import/export location used by admin code
• /usr/local/tomcat/work -> writable JSP compilation cache

Then seed PARM.DOCBASE in local DB to /data/docbase/.

Without that, a large amount of JSP and servlet code will fail on file existence checks even if the JSP compiler itself works.

DB Strategy

Practical Target

Use MySQL-compatible SQL, not H2.

Reasons:

• production points to MySQL-compatible configuration
• legacy SQL and update scripts are written for that family
• dynamic SQL and driver assumptions are unlikely to be portable to H2 without patches

Preferred Seed Plan

The local DB should be assembled in layers, but the first layer should now be the real dump rather than repo SQL alone:

1. import db/dump-pg-202604211927.sql into the local MySQL-compatible container
2. apply local-only overrides for environment-sensitive PARM values
3. import optional auxiliary dumps only if the chosen local workflows need them
4. document one known-good login and one known-good public sample flow
5. only then consider trimming or anonymizing for a lighter-weight developer dataset

This shifts the main implementation work item from “invent a stable dataset” to “stabilize a production-shaped snapshot for local use.”

Required Local Overrides After Import

Even with the real dump, local development still needs a few post-import adjustments.

At minimum, review or override:

• DOCBASE=/data/docbase/
• PATH_TMP=_tmp/
• MAIL_MSG_PATH_MAILER if local mail-template resolution should stay inside the repo/docbase
• any path-oriented PARM values that point at production-only filesystem locations
• any credentials or integration flags that should not target live services from a developer machine

The important change is that users, profiles, access metadata, and most domain rows should come from the real dump first, not from a hand-built minimal seed.

What Will Probably Break First

These are the highest-probability local bring-up failures.

1. Incomplete DB Seed

Most likely symptom:

• menu renders partially or login works but navigation fails
• JSPs throw nulls around Parm, Access, or user profile resolution

2. Missing Filesystem Assets Under DOCBASE

Most likely symptom:

• image checks fail
• CSV import/export paths fail
• mail template lookups fail
• servlet code throws FileNotFoundException or silently renders degraded UI

3. Mixed Legacy Classpaths

Most likely symptom:

• one context starts while the other fails on missing classes, conflicting libs, or older APIs

Running two Tomcat contexts is the easiest way to isolate this.

4. Rewrite And Context Path Assumptions

Most likely symptom:

• .html routes or menu links resolve incorrectly when not hosted exactly like production

This is manageable, but local routing should be explicit.

Estimated Work Breakdown

Phase 1: Container Bring-Up

Expected effort: low to medium.

Deliverables:

• Docker Compose file
• Tomcat Dockerfile or runtime image selection
• exploded mounting of www and rus
• MySQL service
• baseline local environment variables and startup scripts

Phase 2: Local DB Import And Stabilization

Expected effort: medium to high.

Deliverables:

• repeatable import of db/dump-pg-202604211927.sql
• local override script for environment-sensitive PARM rows
• one documented admin test login
• one documented public sample race/photo flow

This is the real critical path.

Phase 3: Runtime Stabilization

Expected effort: medium.

Deliverables:

• working DOCBASE directory layout
• local rewrite compatibility
• sample assets so photo/event pages can render without production storage
• a short smoke-test checklist

The Smallest Sensible First Implementation

If the goal is a usable development environment quickly, the best first slice is:

1. one Tomcat 9 container for www
2. one MySQL container
3. import the real pg dump and apply a small set of local PARM overrides
4. expose the www/admin/menu dashboard first
5. add a second rus context only when a missing admin flow proves it is still needed

If the goal is completeness and fewer hidden assumptions, start with both contexts immediately.

Given the current repo and the server findings, I would still design the Docker setup so a second rus context can be added without reworking the stack.

Recommendation Summary

This is feasible, but the hard part is not Docker.

The hard part is stabilizing a production-shaped local runtime contract across:

• two legacy web trees
• a metadata-driven admin UI
• filesystem-backed application behavior
• a DB that acts as both content store and runtime config store

What It Would Take

• Tomcat 9 on Java 11
• exploded deployment of www, and probably rus as well
• a writable local docbase mounted outside the web roots
• a MySQL-compatible local database
• import of the real pg dump plus a deliberate set of local overrides for environment-sensitive rows
• a short compatibility pass on rewrite behavior and admin links

Overall Assessment

Containerizing the JSP runtime is straightforward.

Making it genuinely useful for local development is still a moderate migration task, but the existence of the real local DB dump changes the shape of the work. The cleanest path is to import the real pg snapshot, override the environment-sensitive parts, treat www as the active acxent runtime, and retain rus as a legacy ablia reference tree unless and until a fresh updated replacement is obtained and decompiled.

Suggested Next Deliverables

If this analysis is accepted, the next implementation docs should be:

1. a concrete docker-compose.yml design
2. a local-db-import-plan.md covering dump import plus local PARM overrides
3. a local-smoke-test.md covering login, admin dashboard, one public event page, and one file-backed operation