# Test Instance Post-Import Runbook

Use this after loading a production database backup into the LAN Redmine test
instance. The goal is to make the test copy safe for Helpdesk, Mailpit, and
redMCP testing.

## Defaults

- Redmine URL: `http://192.168.50.170`
- SSH host: `reddev@192.168.50.170`
- SSH key: `/tmp/reddev`
- Remote Redmine path: `/usr/share/redmine`
- Attachment files root: `/var/lib/redmine/default/files`
- Mailpit host: `192.168.1.105`
- Mailpit ports: HTTP `8025`, SMTP `1025`, POP3 `1110`
- POP3 credentials: `test` / `testpass`
- SMTP authentication: none

## 1. Validate The Fresh Import

Run the read-only validator first:

```sh
./validate_test_instance.py
```

This checks SSH access, Redmine paths, Mailpit connectivity, attachment
directory permissions, controlled test projects, Helpdesk mail settings, and
redMCP Composer metadata when Composer is available.

If Composer is not installed globally, pass a known PHAR:

```sh
./validate_test_instance.py --composer-bin /home/iadnah/projects/redMCP/composer.phar
```

## 2. Fix Attachment Directory Permissions

If the validator reports attachment directory failures, run this on the Redmine
test host:

```sh
sudo chmod -R g+rwX /var/lib/redmine/default/files
sudo find /var/lib/redmine/default/files -type d -exec chmod g+s {} +
```

Verify:

```sh
stat -c "%U %G %a %n" \
  /var/lib/redmine/default/files \
  /var/lib/redmine/default/files/2026 \
  /var/lib/redmine/default/files/2026/04
```

Directories should normally show group-write permissions, such as `2775`.

## 3. Reset Helpdesk Mail Settings

Preview first:

```sh
./reset_helpdesk_mail_settings.py --dry-run
```

Apply:

```sh
./reset_helpdesk_mail_settings.py
```

This rewrites all active `contacts_helpdesk` projects to use Mailpit for POP3
and SMTP. Passwords are written but not printed.

## 4. Restart Passenger

After plugin changes or other code updates, trigger Passenger reload on the
Redmine host:

```sh
ssh -i /tmp/reddev -o IdentitiesOnly=yes reddev@192.168.50.170 \
  'cd /usr/share/redmine && touch tmp/restart.txt'
```

Then hit the site in a browser or with `curl` so Passenger reloads the app.

## 5. Validate Helpdesk Mail

In Redmine, use project `fud-helpdesk` for Helpdesk mail tests.

Incoming test:

1. Send a message into Mailpit.
2. Open `http://192.168.50.170/projects/fud-helpdesk/settings`.
3. Click **Get Mail**.
4. Confirm a Helpdesk issue is created.

Outgoing test:

1. Open the imported Helpdesk issue.
2. Send a Helpdesk response from Redmine.
3. Confirm it appears in Mailpit at `http://192.168.1.105:8025`.

Useful logs:

```sh
ssh -i /tmp/reddev -o IdentitiesOnly=yes reddev@192.168.50.170 \
  'tail -n 100 /usr/share/redmine/log/redmine_helpdesk.log'
```

## 6. Validate redMCP Safe CRUD

Use `fud-nohelpdesk` for issue create/update/delete tests that should not touch
the Helpdesk plugin. Keep API keys in `redMCP/.env`; do not commit that file.

Minimum checks:

```sh
php -l redMCP/app/RedmineClient.php
php -l redMCP/app/redmineClient.php
```

Use the existing redMCP examples in `redMCP/README.md` for read and CRUD smoke
tests against the LAN Redmine copy.

## 7. Run The Helpdesk Smoke Test

After the post-import checks pass, run the live Helpdesk/redMCP smoke test:

```sh
./helpdesk_smoke_test.py
```

This imports a controlled Helpdesk email, verifies `issueWithHelpdesk()`, checks
non-Helpdesk CRUD, confirms default updates do not send Helpdesk email, verifies
explicit outbound Mailpit delivery, and closes the created test ticket. Details
are in `docs/helpdesk_smoke_test.md`.

## 8. Re-Run The Read-Only Validator

Finish by running:

```sh
./validate_test_instance.py
```

The expected result is no `FAIL` lines. `WARN` is acceptable only for optional
local tooling, such as missing global Composer.