Regalamiunsorriso/.github/instructions/regalamiunsorriso-83-149-164-4.instructions.md

---
description: 'Use when: deploying, staging, copying, or promoting regalamiunsorriso site files on server 83.149.164.4, especially for sync/** and www/** changes.'
applyTo: 'sync/**, www/**'
---

# Regalami Un Sorriso Server 83.149.164.4

Instructions in this file are specific to the `regalamiunsorriso` site hosted on server `83.149.164.4` over SSH port `410`.

## Server Access

- SSH user: `marco`
- SSH key: `C:\Users\Maddo\.ssh\id_rsa`
- SSH port: `410`
- Direct SSH login works with the key above.
- The login banner before authentication is expected.

## Preferred SSH Workflow

Use an interactive TTY when a command may need sudo:

```powershell
ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4
```

For root access, use:

```tcsh
sudo tcsh
```

If you need a single elevated command:

```powershell
ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "sudo tcsh -c 'command here'"
```

From PowerShell on Windows, prefer invoking the SSH binary directly instead of wrapping it in `cmd /c`:

```powershell
& 'C:\Windows\System32\OpenSSH\ssh.exe' -tt -i 'C:\Users\Maddo\.ssh\id_rsa' -p 410 'marco@83.149.164.4'
```

## Shell Behavior On This Host

- The remote login shell behaves as `tcsh`.
- POSIX shell constructs like `for ...; do ...; done` fail unless you explicitly run them through `sh -c`.
- The server `sh` does not support `-l`, so use `sh -c`, not `sh -lc`.
- `tcsh` treats redirection and pipelines differently from POSIX shells; commands like `find ... 2>/dev/null | head` can fail with `Ambiguous output redirect` unless the whole payload runs under `sh -c`.
- Prefer one remote command per SSH invocation when doing reconnaissance. Complex commands with pipes, grouped expressions, or escaped parentheses are much more likely to break under PowerShell-to-SSH-to-`tcsh` quoting.
- On Windows PowerShell, avoid `cmd /c "ssh ..."` and `cmd /c "scp ..."` wrappers for anything nontrivial. Nested quoting can collapse before SSH runs and spill later tokens into the local PowerShell session, which leads to misleading local errors such as `sudo: The term 'sudo' is not recognized` or local attempts to run `cksum`.
- Prefer the PowerShell call operator form `& 'C:\Windows\System32\OpenSSH\ssh.exe' ...` and pass the remote command as a single argument when you must stay non-interactive.
- If PowerShell shows the continuation prompt `? >`, the command was malformed locally before SSH executed it. Cancel it and rerun a simpler command instead of trying to answer the prompt.
- If `sudo` reports that a terminal is required, reconnect with `-tt`.
- When running remote commands from PowerShell, quoting can break if the command contains both nested quotes and file paths with spaces.
- For read-only verification commands from PowerShell, prefer `ssh ... --% <remote command>` so the remote command is passed verbatim.
- For `promote-file.sh` calls that target paths with spaces, prefer a local PowerShell loop that passes the full remote command as a single SSH argument instead of building one long nested quoted command.
- For multi-step privileged work, prefer opening one interactive SSH session, then running `sudo tcsh`, then issuing commands sequentially inside that shell. This is more reliable than trying to encode several `sudo tcsh -c 'a ; b ; c'` operations through PowerShell quoting.
- In an interactive `tcsh` root shell, do not re-send a password or any other text starting with `!` after the password prompt has already succeeded. `tcsh` interprets `!` as history expansion and will emit `Event not found`.
- If repeated SSH commands start cancelling or interleaving poorly in the same terminal, rerun them sequentially instead of in parallel.

## Mail Template Runtime Notes

- The server contains multiple `mailMessage` trees:
	- Live web root: `/home/sites/regalamiunsorriso/www/mailMessage`
	- Staging copy: `/home/marco/regalamiunsorriso/incoming/www/mailMessage`
	- Older duplicate trees: `/home/sites/regalamiunsorriso/wwwLang/mailMessage` and `/home/sites/regalamiunsorriso/wwwOld/www/mailMessage`
- During the 2026-04-16 reconnaissance, representative checksums differed between `www/mailMessage` and `wwwLang/mailMessage`, so they are not interchangeable copies.
- The Java application configuration lives under `/home/sites/regalamiunsorriso/rus/WEB-INF`.
- `rus/WEB-INF/web.xml` defines an older or alternate application DB connection as `dbDriver=3`, `database=//localhost/pg`, `user=root`, `password=root`.
- `www/WEB-INF/web.xml` contains the stronger live SQL lead: `dbDriver=17`, `database=//192.168.10.250/pg`, `catalog=pg`, `user=root`, `password=root`, with a description hint `250658#` that corresponds to the server password and an alternate endpoint hint `//localhost:3308/pg`.
- `truckservice.properties` defines a second DB connection as `dbDriver=3`, `dbName=//localhost/truckservice`, `user=root`, `password=root`.
- In this codebase, `dbDriver=3` maps to MySQL Connector/J, not to a legacy non-MySQL driver.
- `dbcomuni.properties`, `rus.properties`, and `truckservice.properties` all set `USE_PARM_HT=true`, which means runtime values are expected to come from the application `Parm` store.
- In code, `DBAdapter.getDocBase()` resolves to `getParm("DOCBASE").getTesto()`, and mail-template lookups use `Parm` values such as `MAIL_REG`, `MAIL_NO_MORE`, `MAIL_NO_MORE_SCAD`, and `MAIL_MSG_PATH_MAILER`.
- In code, `Parm.findByCodice()` reads from `PARM` with `select A.* from PARM AS A where A.codice='...'`, so the live `PARM` table is the authoritative lookup point for these values.
- `pg_src/com/ablia/pg/Users.java` seeds defaults for `MAIL_MSG_RINNOVO` as `mailMessage/rinnovoMsg.html` and `MAIL_MSG_COUPON_OMAGGIO` as `mailMessage/couponOmaggioMsg.html` when the parameters are missing.
- Read-only validation plus later DBeaver confirmation established that the reachable live SQL path is `192.168.10.250:3306`, database `pg`, user `root`, password `root`.
- The `250658#` value should be treated as the server password hint noted in `www/WEB-INF/web.xml`, not as the database password.
- The validated live `PARM` rows included:
	- `DOCBASE=/home/www/regalamiunsorriso/do`
	- `MAIL_MSG_PATH_MAILER=phpmailer/regala_un_sorriso/`
	- `MAIL_NO_MORE=mail_no_more.html`
	- `MAIL_NO_MORE_SCAD=mail_no_more_scad.html`
	- `MAIL_REG=mail_reg.html`
- Because of that indirection, changing files under a `mailMessage` directory is not sufficient proof that outbound mail content will change. The effective `DOCBASE` and mail-template parameter values must also be checked in the live `Parm` data.
- For mail-template reconnaissance, avoid recursing into `/mnt/da1/foto` via the `RUS` symlink unless the task explicitly concerns photo storage. It adds permission noise and did not help identify the email-template source.
- `127.0.0.1:3308` refused connections from the shell during the same investigation, so the localhost hint in `www/WEB-INF/web.xml` should not be treated as the current working shell path without revalidation.
- Do not upload, stage, or leave ad hoc PHP or SQL helper scripts on the server during reconnaissance. Any future live DB query method must be explicitly approved first.

## MCP Limitation

- The MCP SSH tools have not been reliable for this host and previously failed authentication or transport checks.
- Prefer direct terminal SSH commands for this server unless the MCP path is revalidated.

## Site Paths

- Incoming staging root: `/home/marco/regalamiunsorriso/incoming/www`
- Live site root: `/home/sites/regalamiunsorriso/www`

## Tomcat Logs And Runtime Clues

- The active Tomcat installation on this host is under `/usr/local/apache-tomcat-9.0`.
- The most useful live runtime log is `/usr/local/apache-tomcat-9.0/logs/catalina.out`.
- Rotated Tomcat logs are under `/usr/local/apache-tomcat-9.0/logs/`, including files such as `catalina.YYYY-MM-DD.log` and `localhost.YYYY-MM-DD.log`.
- Access to generated JSP work files under `/usr/local/apache-tomcat-9.0/work` may require root.
- A broken JSP on this host can still return `HTTP 200` with a visibly truncated HTML body instead of a clean 500 response; when that happens, fetch part of the page body with `curl -L <url> | head -n ...` and compare the cutoff point with recent `catalina.out` output.

## Staging Workflow

When `www/**` files need deployment:

1. Build the file list from git changes after the initial `www` import baseline.
2. Include any required uncommitted working tree files explicitly if they must be deployed.
3. Copy the selected files into `/home/marco/regalamiunsorriso/incoming/www`, preserving the `www/...` directory structure.
4. Prefer a streamed tar transfer over SSH for batches of files.

Example staging command pattern:

```powershell
tar -cf - -C K:\various\regalamiunsorriso <file-list-under-www> | ssh -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "tar -xf - -C /home/marco/regalamiunsorriso/incoming"
```

- The streamed tar extraction into `/home/marco/regalamiunsorriso/incoming` works as the unprivileged `marco` user and avoids the permission problems seen when uploading an archive and trying to unpack it with `sudo tar`.
- Do not rely on `sudo tar` for staging on this host. `marco` is not permitted to run that extraction as root.

## Promotion Rules

- Promotion to the live site must happen through `sudo tcsh`.
- Do not copy directly as `marco` into `/home/sites/regalamiunsorriso/www`.
- Before replacing an existing live file, capture its exact owner, group, and mode.
- After copy, restore the same owner, group, and mode exactly.
- For new files, use the permissions of surrounding live files of the same type in the same directory.
- If same-extension files in the directory have mixed modes, choose an explicit metadata source file and reuse its owner, group, and mode.

## Promotion Automation

Use these scripts for this site:

- Local helper: `sync/promote-file.sh`
- Local batch helper: `sync/promote-www-remaining.sh`
- Remote helper: `/home/marco/promote-file.sh`
- Remote batch helper: `/home/marco/promote-www-remaining.sh`

### Single File Promotion

Run:

```powershell
ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "sudo tcsh -c '/home/marco/promote-file.sh <staged-path> <live-path> [metadata-source]'"
```

If the source or destination path contains spaces, prefer this PowerShell pattern so SSH receives the remote command as one argument:

```powershell
$remote = "sudo tcsh -c \"/home/marco/promote-file.sh '<staged-path>' '<live-path>' [metadata-source]\""
& ssh -tt -i 'C:\Users\Maddo\.ssh\id_rsa' -p 410 'marco@83.149.164.4' $remote
```

If the deployment needs more than one privileged action or may prompt for a password, prefer this sequence instead of packing everything into one quoted SSH command:

1. Open an interactive SSH session with `-tt`.
2. Run `sudo tcsh`.
3. Run `/home/marco/promote-file.sh ...` commands one at a time.
4. Run `ls -l`, `stat -f`, and `cksum` in that same root shell.

Behavior of `promote-file.sh`:

- If the destination already exists, it copies the file and restores that destination file's original owner, group, and mode.
- If the destination does not exist, it can use an optional third argument as the metadata source file.
- If no third argument is provided for a new file, it falls back to sampling sibling files in the destination directory.

### New PHP Files In Live Root

Root-level PHP files on this site do not all share one mode.

- `/home/sites/regalamiunsorriso/www/_inc_footer.php` is `jenkins:www` with mode `775`
- `/home/sites/regalamiunsorriso/www/gallery1.php` is `jenkins:www` with mode `775`
- `/home/sites/regalamiunsorriso/www/test.php` is `jenkins:www` with mode `644`

For the `faceai_*.php` files, use `/home/sites/regalamiunsorriso/www/_inc_footer.php` as the explicit metadata source.

## Verification

After staging or promotion, verify with:

- `ls -l` for owner, group, and visible mode
- `stat -f` for exact metadata
- `cksum` to compare staged and live file contents
- From PowerShell, prefer `ssh ... --% ls -l ...`, `ssh ... --% stat -f ...`, and `ssh ... --% cksum ...` for verification commands that include quoted paths.

Run verification commands separately if a parallel terminal run becomes unreliable.

## Documentation Expectations

When performing deployments or promotions for this site:

- Record the list of changed files being deployed.
- Distinguish updated files from new files.
- Note whether any deployed file came from the working tree instead of a commit.
- Document every shell quirk or command failure encountered.
- Document the metadata source used for any new live file.
- Update `sync/www-deploy-manifest.md` when the deployment set or procedure changes.