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