redmine/docs/test_instance_post_import.md

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:

./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:

./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:

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

Verify:

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:

./reset_helpdesk_mail_settings.py --dry-run

Apply:

./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:

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:

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:

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:

./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. Validate Helpdesk Outbox Worker Enrichment

When Helpdesk/outbox behavior matters, run the repeatable live validator:

./validate_helpdesk_outbox_worker.py

This creates one controlled Helpdesk ticket through Mailpit, verifies redMCP Helpdesk behavior, checks the matching event_outbox_events rows, and dry-runs worker enrichment without claiming or marking rows processed. Details are in docs/helpdesk_outbox_worker_validation.md.

9. Re-Run The Read-Only Validator

Finish by running:

./validate_test_instance.py

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