# Release Execution Runbook

This runbook is the P6 release gate for TheSol Chat. It must be executed on the exact target host or a staging host restored from the target backup.

---

## 1. Required Inputs

| Input | Example |
|---|---|
| Release tag | `v1.0` |
| Target public URL | `https://chat.example.com/Chatbot` |
| Database name | `thesol_chat` |
| Backup directory | `/var/backups/thesol-chat` or `D:\xampp\chatbot-private\backups` |
| MySQL binary path | `/usr/bin` or `D:\xampp\mysql\bin` |

---

## 2. Pre-Release Backup

Run the backup helper from the application root:

```powershell
php logs/release_backup.php --tag=v1.0 --dir=D:\xampp\chatbot-private\backups --mysql-bin=D:\xampp\mysql\bin
```

Linux example:

```bash
php logs/release_backup.php --tag=v1.0 --dir=/var/backups/thesol-chat --mysql-bin=/usr/bin
```

Expected output:

- A non-empty `.sql` database dump
- A `_manifest.json` file with checksums for source files

Record both paths in `deploy/release-notes-template.md` or the release note created from it.

---

## 3. Restore Proof on Staging

Create an empty staging database, import the dump, and run smoke tests against that restored database.

Windows example:

```powershell
& 'D:\xampp\mysql\bin\mysql.exe' -uroot -p<password> -P3306 -e "CREATE DATABASE thesol_chat_restore_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
Get-Content D:\xampp\chatbot-private\backups\thesol_chat_v1.0_YYYYMMDD_HHMMSS.sql |
  & 'D:\xampp\mysql\bin\mysql.exe' -uroot -p<password> -P3306 thesol_chat_restore_test
```

Linux example:

```bash
mysql -u root -p -e "CREATE DATABASE thesol_chat_restore_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p thesol_chat_restore_test < /var/backups/thesol-chat/thesol_chat_v1.0_YYYYMMDD_HHMMSS.sql
```

Point staging `SB_DB_NAME` at `thesol_chat_restore_test`, then run:

```bash
php logs/preflight_check.php --no-color
php logs/smoke_test_release.php
```

Acceptance: restore succeeds and smoke test returns `0 FAIL`.

---

## 4. Target Host Preflight

Run these commands on the target host after environment variables are set:

```bash
php logs/preflight_check.php --no-color
php logs/smoke_test_release.php
php logs/maintenance.php --dry-run --all
```

Acceptance:

- `preflight_check.php` has `0 FAIL`
- `smoke_test_release.php` has `0 FAIL`
- Maintenance dry run completes without PHP errors

Warnings can be accepted only if recorded in the release notes with a reason and owner.

---

## 5. HTTP Preflight

Run against the public URL, not `localhost`:

```bash
php logs/http_preflight_check.php --url=https://yourdomain.com/Chatbot --no-color
```

Acceptance:

- `0 FAIL`
- Sensitive URLs return 401/403/404/405 or otherwise do not expose private content
- Any WARN is manually checked and recorded

---

## 6. Build Release Package

Run from the repo root:

```bash
php logs/create_release_package.php --tag=v1.0
```

The package excludes:

- `config.php`
- `install.php` / `install1.php`
- `uploads/`
- runtime logs and archives
- local debug helpers
- `.git` / editor metadata

Upload the ZIP to the host, extract into the release directory, then copy production `config.php` or provide all required environment variables.

---

## 7. Manual End-to-End Test

Record evidence in the release notes:

1. Admin login works.
2. Admin settings save persists and reloads.
3. Public chat widget loads.
4. User message creates or reuses a conversation.
5. Agent reply appears in the widget.
6. WhatsApp/MSG91 webhook URL includes token and returns 200 for a valid test payload.
7. MSG91 replay test creates only one message.
8. OTP send + verify completes.
9. Queue worker processes at least one job or `--stats` confirms no backlog.
10. OpenAI troubleshoot completes or records a provider-safe failure.
11. `system-health` has no unacknowledged alert.

---

## 8. Rollback Procedure

Rollback is deliberately manual.

1. Put the app in maintenance mode at the web server or load balancer.
2. Restore the previous code package or checkout the previous Git tag.
3. Restore the DB dump if the release changed data/schema:

Windows:

```powershell
Get-Content D:\xampp\chatbot-private\backups\thesol_chat_v1.0_YYYYMMDD_HHMMSS.sql |
  & 'D:\xampp\mysql\bin\mysql.exe' -uroot -p<password> -P3306 thesol_chat
```

Linux:

```bash
mysql -u root -p thesol_chat < /var/backups/thesol-chat/thesol_chat_v1.0_YYYYMMDD_HHMMSS.sql
```

4. Re-run:

```bash
php logs/preflight_check.php --no-color
php logs/smoke_test_release.php
```

5. Remove maintenance mode only after smoke test returns `0 FAIL`.

---

## 9. Final Tag

Only tag final release after all P6 gates pass on target:

```bash
git tag -a v1.0 -m "TheSol Chat v1.0 production release"
git push origin v1.0
```

Do not tag final release from local-only evidence.
