# TakafulHub 2.0 release preparation

**Release candidate:** `v2.0.0-rc.2`
**Status:** prepared for infrastructure provisioning and restricted staging; 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.2`. The prior `v2.0.0-rc.1` tag remains preserved as the preceding release candidate.

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 change note

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`

## 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. Obtain owner approval for commercial values, VastPro hierarchy and distribution configuration.
6. 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, registrations, Leads, Credit Packages, VastPro Credit Pricing and Commercial Settings.
5. Use QA recipients only for password reset, Support reply and portal-aware notification emails; verify SPF/DKIM/DMARC.
6. On staging/sandbox first, test CHIP Card, available FPX, failed/cancelled payment, callback replay and exactly-once fulfilment.
7. Use only a clearly labelled synthetic lead to verify screening, attribution, routing, assignment and Lead Credit deduction. Do not publish Takaful.Online.
8. 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.