PostGIS launch file and standalone integration instructions

changelog.md

@@ -1,5 +1,21 @@
 # OSCAR Build Node Change Log
 All notable changes to this project will be documented in this file. 
+
+## 3.5.1 2026-05-07
+### Added
+- Added `monitor-oscar.ps1` as the preferred Windows monitoring entrypoint for sessionless launches.
+- Added documented sessionless launch patterns for Windows and Linux production operation.
+- Added documented auto-start guidance for Windows Task Scheduler and Linux `systemd`.
+
+### Changes
+- Updated packaged-release documentation to make sessionless `launch-all` the default production launch path.
+- Updated monitoring documentation to explain duplicate-monitor protection and where operators should check `monitor.last-status`, `monitor.last-error`, `monitor.out`, and `monitor.err`.
+- Updated reset/redeploy guidance to explain that operators may need to stop the monitor wrapper, remove the extracted release directory, re-extract the ZIP, recreate `.env`, and relaunch sessionlessly when old runtime artifacts or stale lanes persist.
+- Updated MediaMTX guidance to be more succinct and to explain that MediaMTX reduces load on the Java backend by proxying and stabilizing camera connections before OSCAR consumes them.
+
+### Fixes
+- Improved operational guidance around already-running OSCAR backends versus already-running monitor wrappers so sessionless launches fail more clearly.
+
 ## 3.5.0 2026-04-24
 ### Changes
 - Updated LaneSystem README

dist/documentation/MediaMTX_OSCAR_camera_proxy_guide.md

@@ -0,0 +1,191 @@
+# Using MediaMTX to Reduce OSCAR Camera Stream Load
+
+This guide shows the recommended **MediaMTX** pattern for camera-heavy OSCAR deployments.
+
+The short version is simple: put MediaMTX between OSCAR and the physical cameras, point the OSCAR lane CSV at the MediaMTX RTSP paths, validate the camera profile with `monitor-oscar`, and then use `launch-all` for routine production starts.
+
+## Why MediaMTX helps
+
+Without a proxy, OSCAR opens direct RTSP sessions to each camera endpoint referenced by the lanes. At larger scale, that increases:
+
+- Java-side camera session setup work
+- reconnect churn when cameras or networks wobble
+- socket and thread churn around repeated stream handling
+- load on the physical cameras when many logical lanes reuse the same feeds
+
+MediaMTX reduces that burden by presenting OSCAR with a smaller set of stable local RTSP paths. The proxy owns the upstream camera connections, while the Java backend talks to local endpoints instead of repeatedly reconnecting to every physical camera.
+
+## Recommended operating model
+
+- Use `monitor-oscar` during first-run validation, troubleshooting, burn-in, and camera-profile testing.
+- Use `launch-all` for routine production after the camera profile is accepted.
+- Keep MediaMTX on the OSCAR host or a nearby LAN host whenever possible.
+
+## Sony camera settings to use
+
+For Sony cameras, use the following secondary-stream settings:
+
+- `H.264`
+- `640x480`
+- `15 fps`
+- `1 s` keyframe interval when possible
+- `high` H.264 profile
+- `CBR`
+- about `4000 kbps`
+
+These settings are a good match for lightweight proxying and testing because they keep the stream modest while still providing stable H.264 output.
+
+## Minimal MediaMTX configuration
+
+Use a lightweight RTSP-only profile unless you explicitly need other protocols. In the yaml file below lane01_cam and lane02_cam configure Sony cameras with video codec number one and lane03_cam and lane04_cam configure Axis cameras. Edit the username, password, and IP address information and configure the Sony codec before using this file. 
+
+```yaml
+api: yes
+apiAddress: :9997
+rtmp: no
+hls: no
+webrtc: no
+srt: no
+paths:
+  lane01_cam:
+    source: "rtsp://<user>:<password>@192.168.8.2/554/media/video1"
+    sourceOnDemand: yes
+    sourceProtocol: tcp
+
+  lane02_cam:
+    source: "rtsp://<user>:<password>@192.168.8.5/554/media/video1"
+    sourceOnDemand: yes
+    sourceProtocol: tcp
+  lane03_cam:
+    source: "rtsp://<user>:<password>@192.168.8.73/axis-media/media.amp?adjustablelivestream=1&resolution=640x480&videocodec=h264&videokeyframeinterval=15"
+    sourceOnDemand: yes
+    sourceProtocol: tcp
+
+  lane04_cam:
+    source: "rtsp://<user>:<password>@192.168.8.229/axis-media/media.amp?adjustablelivestream=1&resolution=640x480&videocodec=h264&videokeyframeinterval=15"
+    sourceOnDemand: yes
+    sourceProtocol: tcp
+```
+
+### Why these settings are recommended
+
+- `sourceOnDemand: yes` avoids pulling upstream video when OSCAR is not using the path.
+- `sourceProtocol: tcp` is usually the most predictable RTSP transport on real LANs, VPNs, and NATed paths.
+- Disabling `rtmp`, `hls`, `webrtc`, and `srt` keeps MediaMTX focused on simple RTSP proxying.
+- The API on port `9997` gives you a quick way to verify that the paths are present.
+
+## OSCAR CSV pattern
+
+The OSCAR CSV should point camera fields at the MediaMTX host and path, not at the physical camera.
+
+```csv
+Name,UniqueID,AutoStart,Latitude,Longitude,RPMConfigType,RPMHost,RPMPort,AspectAddressStart,AspectAddressEnd,EMLEnabled,EMLCollimated,LaneWidth,CameraType0,CameraHost0,CameraPath0,Codec0,Username0,Password0,CameraType1,CameraHost1,CameraPath1,Codec1,Username1,Password1
+sim-0,simu-0,FALSE,35.89,-84.19,Rapiscan,192.168.8.77,1601,,,FALSE,FALSE,4.820000172,Custom,192.168.8.77:8554,/lane03_cam,,,,Custom,192.168.8.77:8554,/lane04_cam,,,
+```
+
+### Important fields
+
+- `RPMHost` and `RPMPort` still point to the SRLS, Rapiscan, or emulator service.
+- `CameraType*` should be `Custom` when you want OSCAR to use the host and path directly.
+- `CameraHost*` should point to the machine running MediaMTX, usually `<host>:8554`.
+- `CameraPath*` should point to the MediaMTX path, such as `/lane03_cam`.
+- `Username*` and `Password*` can usually remain blank because MediaMTX authenticates to the physical camera upstream.
+
+## Quick setup
+
+### 1. Start MediaMTX
+
+Linux:
+
+```bash
+./mediamtx mediamtx.yml
+```
+
+Windows PowerShell:
+
+```powershell
+.\mediamtx.exe mediamtx.yml
+```
+
+### 2. Verify that MediaMTX is listening
+
+Linux:
+
+```bash
+ss -ltnp | grep -E '8554|9997'
+```
+
+Windows PowerShell:
+
+```powershell
+Get-NetTCPConnection -LocalPort 8554,9997 -State Listen
+```
+
+### 3. Verify the API
+
+Linux or macOS:
+
+```bash
+curl http://127.0.0.1:9997/v3/paths/list
+```
+
+Windows PowerShell:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:9997/v3/paths/list
+```
+
+### 4. Point OSCAR at the proxy
+
+Update the lane CSV so each camera host and path points to MediaMTX instead of the physical device, then upload the CSV through the **Services** tab in the OSCAR admin page.
+
+## Camera profile guidance
+
+For larger systems, keep the streams modest unless you have already validated a heavier profile. A practical starting point is:
+
+- H.264
+- 640x480
+- 15 fps
+- CBR
+- 1-second keyframe interval when possible
+
+Those settings reduce total decode and transport cost while still giving OSCAR useful video.
+
+## Fast troubleshooting
+
+### OSCAR cannot open the stream
+
+Check:
+
+- MediaMTX is running
+- the path name matches exactly
+- the lane CSV points to the correct host and path
+- port `8554` is reachable from the OSCAR host
+
+Quick direct test:
+
+```bash
+ffplay rtsp://127.0.0.1:8554/lane03_cam
+```
+
+### The path exists but does not pull video
+
+Check:
+
+- upstream camera IP, credentials, and path
+- whether the camera supports the requested stream format
+- whether the camera accepts RTSP over TCP
+
+### Reconnect churn is still high
+
+MediaMTX reduces Java-side reconnect pressure, but it cannot fix every upstream problem. Also check:
+
+- camera network stability
+- encoder configuration
+- duplicate consumers
+- emulator-side or payload-side issues
+- OSCAR thread and reconnect logs from the monitor directory
+
+## Summary
+
+MediaMTX reduces the burden on the OSCAR Java backend by replacing many direct camera sessions with a smaller set of local RTSP proxy paths. That usually means less reconnect churn, less socket and thread churn, easier lane reuse, and a simpler camera topology for large test or production systems.

dist/documentation/Node_Administration_3.5.1_addendum.md

@@ -0,0 +1,32 @@
+# Node Administration 3.5.1 addendum
+
+The existing **Node Administration** PDF remains useful for Admin UI tasks such as:
+
+- starting and stopping modules
+- adding users and roles
+- configuring sensors, storage, and SOS services
+
+No major Admin UI workflow changes were required for the 3.5.1 launch, monitoring, and packaging updates.
+
+The operational changes for 3.5.1 are outside that PDF and are now covered in these updated deployment documents:
+
+- `Release_Notes_3.5.1.md`
+- `OSCAR_launch_monitoring_guide.md`
+- `MediaMTX_OSCAR_camera_proxy_guide.md`
+- `OSCAR_System_Documentation_Manual_3.5.md`
+
+Use the PDF for Admin Panel behavior, and use the updated deployment documents for:
+
+- Java 21 and Docker prerequisites
+- `.env` setup
+- already-running OSCAR handling
+- launch-mode selection: `launch-all` for efficient production, `monitor-oscar` for validation, troubleshooting, and system profiling
+- sessionless production starts with `launch-all` on Linux and Windows
+- automatic production startup after reboot with `systemd` on Linux or Task Scheduler on Windows
+- monitoring and status scripts, including duplicate-monitor prevention
+- the new Windows PowerShell monitor wrapper `monitor-oscar.ps1`
+- the preferred hidden PowerShell `Start-Process` pattern for monitored Windows runs
+- fresh-install cleanup of older OSCAR releases
+- MediaMTX-assisted camera deployment guidance, now shortened and focused on Java-backend load reduction
+
+The updated monitor wrappers include single-instance protection so a second live monitor launch is refused until the first one is stopped. Use the monitor wrappers when detailed diagnostic evidence is needed; use `launch-all.sh` or `launch-all.bat` for routine production operation to avoid unnecessary monitoring logs and snapshot artifacts.

dist/documentation/OSCAR_System_Documentation_Manual_3.5.md

@@ -86,7 +86,7 @@ The diagram below condenses the system relationships. It is not a source-code cl
 
 # 3. Installation and initial startup
 
-Installation is intentionally simple: download a release archive, extract it, ensure Docker is installed and running, and launch the platform with the OS-specific launch-all script (`launch-all.bat` for Windows, `launch-all.sh` for Linux/macOS, or `launch-all-arm.sh` for ARM systems). The database and application come up together in the default deployment path.
+Installation is intentionally simple: download a release archive, extract it, ensure Docker is installed and running, and launch the platform with the OS-specific `launch-all` script (`launch-all.bat` for Windows, `launch-all.sh` for Linux/macOS, or `launch-all-arm.sh` for ARM systems). `launch-all` is the preferred efficient production startup path because the database and application come up together without the extra monitoring logs and profile artifacts produced by the monitor wrapper. Use `monitor-oscar` instead for first-run validation, burn-in, troubleshooting, side-by-side evaluation, or system profiling.
 
 ## Prerequisites
 
@@ -105,7 +105,11 @@ Installation is intentionally simple: download a release archive, extract it, en
 >
 > 2\. Install Docker and verify that the Docker service is running before starting OSCAR.
 >
-> 3\. Run the launch-all script (`launch-all.bat`, `launch-all.sh`, or `launch-all-arm.sh`) for the operating system in use. In the default path, the script starts PostgreSQL locally in Docker and then starts the Java application.
+> 3\. For efficient production operation, run the `launch-all` script (`launch-all.bat`, `launch-all.sh`, or `launch-all-arm.sh`) for the operating system in use. In the default path, the script starts PostgreSQL locally in Docker and then starts the Java application.
+>
+>    Sessionless production is the preferred operating mode once the deployment has been validated. On Linux, a common pattern is `nohup ./launch-all.sh > launch.out 2>&1 &`. On Windows, the recommended hidden start pattern is a PowerShell `Start-Process` call that runs `launch-all.bat` with stdout and stderr redirected to log files.
+>
+>    For first-run validation, troubleshooting, burn-in, side-by-side evaluation, or system profiling, run `monitor-oscar` instead. The monitor path intentionally creates additional logs, snapshots, JFR checks, thread dumps, and database trend files so operators can evaluate system behavior before or during investigation. Windows monitored runs now also have a PowerShell-first wrapper, `monitor-oscar.ps1`, which is the preferred hidden or redirected entry point for sessionless monitored launches.
 >
 > 4\. Open the application on the configured port. Port 8282 is the baseline HTTP application port, and 8443 is a representative HTTPS configuration.
 >
@@ -127,6 +131,60 @@ Installation is intentionally simple: download a release archive, extract it, en
 </tbody>
 </table>
 
+## Sessionless and restart-safe launch patterns
+
+For normal production use, `launch-all` should be treated as the default startup path, whether the system is started interactively or headlessly.
+
+### Linux production
+
+Interactive:
+
+```bash
+./launch-all.sh
+```
+
+Sessionless:
+
+```bash
+nohup ./launch-all.sh > launch.out 2>&1 &
+```
+
+For automatic restart after reboot, the recommended pattern is a small `systemd` unit that runs `launch-all.sh` after `docker.service` is available.
+
+### Windows production
+
+Interactive:
+
+```bat
+launch-all.bat
+```
+
+Sessionless from PowerShell:
+
+```powershell
+Start-Process powershell.exe `
+  -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-Command',"Set-Location -LiteralPath '$PWD'; .\launch-all.bat" `
+  -WindowStyle Hidden `
+  -RedirectStandardOutput "$PWD\launch.out" `
+  -RedirectStandardError "$PWD\launch.err"
+```
+
+For automatic restart after reboot, the recommended pattern is a **Task Scheduler** task with an **At startup** trigger that runs `launch-all.bat` from the extracted OSCAR directory after Docker is available.
+
+### Windows monitored diagnostics
+
+For monitored validation or troubleshooting, the preferred Windows wrapper is `monitor-oscar.ps1`.
+
+```powershell
+Start-Process powershell.exe `
+  -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File',"$PWD\monitor-oscar.ps1" `
+  -WindowStyle Hidden `
+  -RedirectStandardOutput "$PWD\monitor.out" `
+  -RedirectStandardError "$PWD\monitor.err"
+```
+
+This keeps the monitoring window hidden while preserving redirected output for later review.
+
 ## Ports and first-run behaviors
 
 | **Area**                   | **Typical value or behavior**                          | **Interpretation**                                                                                                   |
@@ -396,6 +454,16 @@ Default deployment begins to strain as lane counts, event volume, and camera cou
 
 A practical target profile for scaled deployments is 640x480 at about 5 frames per second, while 1080p may be acceptable on smaller systems. Camera settings should be chosen with total system scale in mind. For a 50-lane or 100-camera target, the aggregate cost of 1080p video is likely excessive.
 
+## MediaMTX as a scale helper
+
+When many logical lanes reuse a smaller number of physical camera feeds, MediaMTX can reduce the burden on the OSCAR Java backend by replacing many direct RTSP sessions with a smaller set of stable local proxy paths. In practice, that lowers Java-side reconnect churn, reduces repeated camera-side socket activity, and simplifies lane CSV reuse in larger systems.
+
+## Launch mode selection for operations
+
+Use `monitor-oscar` when deployment teams need evidence: first-run validation, burn-in testing, troubleshooting, camera-profile comparisons, memory and thread profiling, or PostgreSQL session analysis. The monitor wrapper is intentionally verbose and creates monitor directories, periodic snapshots, thread dumps, JFR status checks, and database trend files.
+
+Use `launch-all` for efficient production operation once the system profile has been validated. This keeps routine startup simple and avoids collecting detailed monitoring artifacts when no in-depth system profile is required. In production, prefer a sessionless `launch-all` start or an automated restart-safe wrapper such as `systemd` on Linux or Task Scheduler on Windows.
+
 ## What stays where in a split deployment
 
 When PostgreSQL is moved off the application host, videos and the other stored files remain on the application server. In practice, that means the application tier continues to own the file system while the database tier handles relational persistence. This is important for storage planning, backups, and role-based file retrieval.
@@ -450,7 +518,7 @@ This section captures known gaps and enhancement ideas so they are not confused
 
 > 1\. Install Docker and verify that the service is running on the host before launch.
 >
-> 2\. Extract the chosen OSCAR release and start it with the OS-specific launch-all script (`launch-all.bat`, `launch-all.sh`, or `launch-all-arm.sh`).
+> 2\. Extract the chosen OSCAR release and start production operation with the OS-specific `launch-all` script (`launch-all.bat`, `launch-all.sh`, or `launch-all-arm.sh`). Use `monitor-oscar` instead when the goal is validation, troubleshooting, burn-in, side-by-side comparison, or system profiling.
 >
 > 3\. Change the initial admin password using the package-provided settings file and password-initialization script before production use.
 >