# TakafulHub 2.0 release preparation

**Release candidate:** `v2.0.0-rc.5`
**Status:** release-candidate cutover work is complete locally; authenticated browser UAT and release approval remain required. Not deployed.
**Scope:** TakafulHub, VastPro and Sites Admin. Takaful.Online remains Draft and is not part of this launch.

This is the authoritative deployment, rollback and controlled-UAT runbook. It contains placeholders only; production credentials and customer data must never be added to this document or the repository.

## Release manifest and artifact

Create an annotated local release tag only after the release repository has a reviewed commit: `v2.0.0-rc.5`. Earlier release-candidate tags remain preserved as historical artifacts.

The deployment artifact is reproducible from that commit and includes source, `composer.lock`, `package-lock.json`, `vendor/` or its Composer-install contract, `public/build/`, source-managed `public/` assets, migrations, configuration, routes and views. It excludes `.env*` except `.env.example`, local databases, `node_modules`, logs, cache, uploads, QA screenshots and IDE files.

## RC2 domain contract

The production domain contract is migrated to `app.takafulhub.io` (TakafulHub Agent/Admin), `sites.takafulhub.io` (Sites Admin), and `vastpro.app` (VastPro). `takafulhub.com` is released for a future database-managed public Website and is no longer an application host.

Verify these root-public assets are shipped even though Vite leaves their absolute URLs untouched:

- `public/images/vastpro/great-eastern-takaful-logo.png`
- `public/assets/brand/THLogo_004.png`
- `public/assets/payment/visa_icon.png`
- `public/assets/payment/mastercard_icon.png`

## RC5 registration-lifecycle cutover

RC5 introduces the cross-portal registration email-OTP lifecycle. It is a schema-and-code cutover: the code is **not** compatible with the pre-RC5 schema because it needs the OTP table and lifecycle columns. A previous application artifact must not remain online after new OTP lifecycle records are accepted.

Before the cutover window, take and verify an encrypted database backup and confirm the queue worker can process portal-aware mail. During the controlled window:

1. Enable maintenance/read-only handling if the host supports it and drain/restart workers deliberately.
2. Deploy the RC5 artifact and install its locked dependencies/build assets.
3. Run `php artisan migrate --force` exactly once.
4. Rebuild caches and restart workers on the RC5 artifact.
5. Immediately run the OTP/Admin smoke checks below before reopening registration traffic.

The migrations are additive. They create `email_verification_otps`, add nullable `users.registration_verification_version`, and add the VastPro OTP/rejection-history columns. Existing VastPro `pending` rows are mapped to `pending_admin_approval` with verification version `legacy`; no email-verification timestamp, user, profile, membership, Lead Credit, payment or hierarchy relationship is fabricated. Existing normal TakafulHub `NULL` verification versions retain legacy signed-link behaviour.

Do not use an automatic down migration as routine rollback after traffic resumes. If the RC5 application must be rolled back before any new OTP state exists, restore only to a demonstrably schema-compatible application/database pair. After new lifecycle data exists, preserve the data and use a forward fix or a tested restore plan.

## Production environment contract

| Group | Variables | Required | Validation |
|---|---|---:|---|
| App | `APP_ENV=production`, `APP_DEBUG=false`, HTTPS `APP_URL`, stable `APP_KEY`, dedicated `IC_HASH_KEY` | Yes | `GET /up`, login and encryption operations work; keys remain stable between releases. |
| Portals | `TAKAFULHUB_PORTAL_URL`, `VASTPRO_PORTAL_URL`, `SITES_PORTAL_URL`; matching `*_PORTAL_HOSTS` | Yes | Exact production hosts only; edge proxy rejects unknown hosts. |
| Database | `DB_CONNECTION=mysql`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `DB_CHARSET=utf8mb4`, `DB_COLLATION` | Yes | InnoDB/strict mode, backup and `migrate:status` confirmed. |
| Session/cache | `SESSION_DRIVER=database`, `CACHE_STORE=database`, `SESSION_SECURE_COOKIE=true`, `SESSION_HTTP_ONLY=true`, `SESSION_SAME_SITE=lax` | Yes | Secure cookies; database session/cache tables writable. |
| Proxy | `TRUSTED_PROXIES` | Behind proxy | Comma-separated known proxy IPs/CIDRs only; never `*`. |
| Queue | `QUEUE_CONNECTION=database`, optional `DB_QUEUE_CONNECTION`, `DB_QUEUE`, `QUEUE_FAILED_DRIVER=database-uuids` | Yes | Supervised worker handles a safe notification; failed jobs visible. |
| Mail | `MAIL_MAILER`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_ENCRYPTION`, `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | Yes | Controlled QA delivery and portal CTA URLs pass. |
| CHIP | `CHIP_API_KEY`, `CHIP_BRAND_ID`, `CHIP_API_BASE_URL`, `CHIP_PUBLIC_KEY` | Before payment | Correct environment, methods, callback signature and exactly-once fulfilment tested. |
| Storage | `FILESYSTEM_DISK`, or `AWS_*`/`AWS_BUCKET`/`AWS_URL`/`AWS_ENDPOINT` | Yes | Release-independent uploads, public URL and backup verified. |
| Logging | `LOG_CHANNEL`, `LOG_STACK`, `LOG_LEVEL`, `LOG_DAILY_DAYS` | Yes | Retention, alerting and owner established. |

All secrets are provisioned outside Git. Do not copy local `.env` values into staging or production.

## Domain, server and runtime contract

- TakafulHub Agent/Admin: `https://app.takafulhub.io`
- VastPro: `https://vastpro.app`
- Sites Admin: `https://sites.takafulhub.io`
- Managed Sites: database-driven custom domains, including the future public `https://takafulhub.com`; deployment never publishes a Draft Website.
- CHIP callback: `https://app.takafulhub.io/payments/chip/callback` when `APP_URL` is the TakafulHub HTTPS URL.

The web server must use `public/` as document root, terminate HTTPS, redirect HTTP to HTTPS, forward trusted host/proto/client-IP headers, serve `public/build` and public assets, and pass PHP requests to PHP-FPM or equivalent. Configure 5 MB-plus upload limits for Sites assets, safe timeouts and host allow-lists. Use PHP **8.3+** with Laravel/PDO-MySQL, OpenSSL, mbstring, tokenizer, XML/DOM, cURL, fileinfo and JSON support. Build assets in CI/release workspace with `npm ci`; do not update dependencies during deployment.

## Deployment runbook

### Pre-deployment

1. Approve a reviewed release commit and annotated tag; record its hash in the deployment ticket.
2. Verify completed, readable, encrypted DB and persisted-upload backups, retention and restore owner.
3. Confirm production DB compatibility and inspect `php artisan migrate:status` against production.
4. Confirm hosts, DNS/HTTPS/proxy allow-list, storage, mail, queue supervisor and scheduler are provisioned.
5. Confirm both portal sender identities and reply-to policy, SMTP authentication, SPF, DKIM and DMARC with a controlled QA recipient. OTP delivery is a launch dependency, not a best-effort optional notification.
6. Obtain owner approval for commercial values, VastPro hierarchy and distribution configuration.
7. Keep `MEMBERSHIP_AUTO_RENEW_ENABLED=false`; do not publish Takaful.Online.

### Build and deploy

```bash
composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction
npm ci
npm run build
php artisan migrate --force
php artisan storage:link
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
```

Never use `composer update`, `migrate:fresh`, `db:seed`, or automatic down migrations in production. A `releases/<id>` + shared `.env`/`storage` + atomic `current` symlink pattern is recommended where supported.

Supervise a database queue worker sized by the infrastructure, for example:

```bash
php artisan queue:work database --sleep=3 --tries=3 --backoff=60,300,900 --max-time=3600
```

Install one scheduler invocation every minute:

```bash
* * * * * cd /path/to/current && php artisan schedule:run >> /dev/null 2>&1
```

Current scheduled work: lead reminders every five minutes, membership-notification processing daily at 07:15 Asia/Kuala_Lumpur, and the gated Auto-Renew processor hourly.

### Post-deployment controlled UAT

1. Verify `GET /up`, HTTPS redirects, portal hosts, login, sessions, storage assets and no debug pages.
2. Verify TakafulHub: Dashboard, Membership, E-Wallet, Lead Credits, Leads, Billing, Support and notification bell.
3. Verify VastPro: Dashboard, no Membership, Premium Lead readiness, My Leads, Team, E-Wallet, Credits, Billing and Support.
4. Verify Admin: Dashboard, normal registrations, VastPro registrations, Leads, Credit Packages, VastPro Credit Pricing and Commercial Settings. Admin may review only OTP-verified new registrations; legacy mapped VastPro rows remain reviewable.
5. Use QA recipients only to verify one TakafulHub OTP, one VastPro OTP, password reset, Support reply and portal-aware notification emails. Confirm sender identity, portal-correct CTA URL, expiry/resend messaging and SPF/DKIM/DMARC.
6. Confirm an unverified/pending/rejected registration cannot obtain an authenticated operational session or reach an operational route; confirm approved and active accounts can.
7. On staging/sandbox first, test CHIP Card, available FPX, failed/cancelled payment, callback replay and exactly-once fulfilment.
8. Use only a clearly labelled synthetic lead to verify screening, attribution, routing, assignment and Lead Credit deduction. Do not publish Takaful.Online.
9. Verify Partner withdrawal lifecycle only with synthetic data; it is not an automated payout flow.

## Rollback and recovery

- **Application defect:** roll back to a schema-compatible prior artifact.
- **Configuration defect:** correct/revert configuration, rebuild caches and restart workers.
- **Worker defect:** stop/restart workers on compatible code.
- **Payment callback defect:** preserve payment events/orders/attempts and reconcile.
- **Financial defect:** stop affected operations and reconcile; never blindly restore or down-migrate wallet, credit, membership, payment, renewal, conversion or partner tables.
- **Migration defect:** assess schema/data before action. A DB restore is disaster recovery, not routine app rollback after live transactions.

A restore drill must prove DB/uploads restore, stable app key/config, cache rebuild, worker restart, login and ledger visibility in a safe environment.

## Initial release gates

Initial scope can include TakafulHub, Admin and VastPro only after this runbook is completed. One-time CHIP payment requires separate controlled validation. These remain off/not launched:

- Membership Auto-Renew (`MEMBERSHIP_AUTO_RENEW_ENABLED=false`)
- Takaful.Online and every Draft Site
- unverified CHIP production methods/integrations
- real Partner payouts before operational sign-off

Before go-live, owner/Admin must verify Membership pricing, both portal Credit Package pricing/availability, both conversion rates/enabled states, coupons, affiliate/partner allocations, withdrawal policy, VastPro Agency/Whole Group/Direct Group/ranks/active agents, operator queues, eligibility, work/vacation state and intended Lead Credit balances.

## Known non-blocking limitations

- Vite leaves two root-public asset URLs unresolved at build time; both must be present in the artifact and verified at runtime.
- The deprecated per-Website legal mutation path is a **Sites Pre-Launch P2**, not a core deployment blocker.
- Takaful.Online is `takaful_online` / `takaful.online` / **Draft**.
- Production infrastructure is intentionally not validated from localhost.