# Production Migration Readiness

## Purpose and decision boundary

This document assesses migration of the current Windows/XAMPP VtigerCRM and `ucm_integration` workload to Linux. It is an assessment, not migration authorization. The assessed implementation baseline is commit `baa94ce`, tag `phase9r1-dev-validated`.

The recommended sequence preserves the legacy AMI listener as the production CRM authority during the platform move. CEM follower, Event Journal and CRM Consumer may run in validated shadow mode, but CEM ownership must be promoted in a separate change after Linux parity is proven.

Current decision: **PRODUCTION_MIGRATION_READY_WITH_BLOCKERS**. The target foundation and rollback design are suitable for a rehearsal, but source-system facts, export sizing, service definitions, network approval, certificate handling and a timed restore rehearsal remain mandatory gates.

## DEV Linux inventory

Inventory captured on 2026-08-08 without loading secrets or writing to databases:

| Area | Observed DEV state |
| --- | --- |
| Host | Ubuntu 24.04 LTS, Linux 6.8, host `ubuntu24` |
| Web | Apache 2.4.58; HTTP and HTTPS vhosts use the shared web root; PHP, rewrite, headers and TLS modules loaded |
| PHP | PHP 8.3.6; required `curl`, `mbstring`, `mysqli`, `openssl`, `sockets`, XML and ZIP support present |
| Database | MariaDB 10.11.14 binaries installed and service active; server charset/collation were not readable without credentials and remain unverified |
| Vtiger | DEV tree is Vtiger 8.4.0; application storage, cache and logs are owned by the web runtime identity |
| Integration | Repository contains legacy AMI listener, TCP/WebSocket bridge, CEM follower, aggregate persistence, Event Journal, CRM consumer, authority controls and recording services |
| MarvelPBX | Installable package and active DEV module/layout integration exist; recording-management foundation was validated at the baseline tag |
| Processes | Apache, MariaDB, legacy listener, WebSocket bridge, CEM follower, Event Journal and CRM consumer were observed on DEV |
| Scheduling | A disabled AMI systemd unit and Vtiger timer definitions exist; archive cron variants exist, with production-oriented producer/worker entries disabled |
| Recording | UCM HTTPS resolver/REC transport, Marvel playback proxy and policy layer exist; recording bytes remain on UCM/NAS |
| TLS/CA | Apache TLS vhost is enabled. No reviewed application-specific CA/certificate artifact was identified in the integration tree; dependency example certificates are not deployment trust material |
| Runtime | CEM capture, aggregate, journal, checkpoint, authority and consumer state is under ignored runtime directories; these files are not migration inputs by default |
| Permissions | Sensitive local configs are mostly owner-only; the CRM production-consumer local config and a legacy-observation backup have group/other bits and require review before reuse |
| Backups | A system backup root exists, but no complete, recent, restorable production migration set was proven by repository evidence |

Exact DEV installation paths are operational facts and intentionally are not migration contracts. The readiness tool accepts both roots as arguments.

## Windows production facts: known and unknown

Repository evidence establishes that the source is Windows/XAMPP and that legacy CRM behavior, popup delivery, PBXManager data and MarvelPBX customizations must be preserved. It does **not** establish the following, so these are blockers rather than assumptions:

- Windows and XAMPP release, Apache/PHP/MySQL or MariaDB versions and PHP extensions;
- production Vtiger release, hotfixes, custom modules, core edits and installed MarvelPBX package revision;
- database size, storage engines, charset/collation mix, SQL modes, routines, triggers, events and view definers;
- attachment/storage size, locations, ACLs and growth rate;
- active Windows services, scheduled tasks, listener launch method, log rotation and backup jobs;
- public vhost, DNS TTL, certificate chain/private-key custody, firewall/NAT and allowed origins;
- UCM AMI/API allowlists, TLS trust chain, NAS/archive mounts and routing from the Linux target;
- current user concurrency, write rate, acceptable outage, RPO/RTO and business owner approval.

These facts must be inventoried on the source and signed off before the final export.

## Migration scope classification

| Scope | Classification | Required treatment |
| --- | --- | --- |
| A. Vtiger application code | NEEDS_EXPORT | Inventory exact source version and custom drift; deploy a reviewed Linux release, not an unexamined XAMPP tree |
| B. Vtiger database | NEEDS_EXPORT | Consistent final dump, restore rehearsal, charset/schema/view validation and record-count reconciliation |
| C. `ucm_integration` code | READY | Deploy the validated tagged tree; recreate local configuration and do not copy working-tree/runtime debris |
| D. MarvelPBX module | READY | Install the validated package, then verify schema lifecycle, list/detail and recording proxy against restored data |
| E. AMI listener/runtime | NEEDS_REBUILD | Recreate configuration and supervised Linux service; preserve legacy authority |
| F. WebSocket bridge | NEEDS_REBUILD | Recreate reviewed origin/auth/port configuration and supervised service |
| G. CEM services | NEEDS_REBUILD | Deploy code but create fresh runtime state; start shadow/non-authoritative after legacy parity |
| H. Recording configuration | NEEDS_EXPORT | Securely recreate encrypted settings, UCM endpoint policy and CA trust; do not move recording bytes by default |
| I. TLS/certificates | NEEDS_REBUILD | Prefer newly issued target certificates; otherwise securely transfer approved keys with documented custody |
| J. Scheduled jobs | NEEDS_REBUILD | Translate and deduplicate Windows tasks into reviewed systemd timers/cron jobs |
| K. Permissions/ownership | NEEDS_REBUILD | Establish dedicated service identities, least privilege and restrictive secret/runtime modes |
| L. Logs/runtime state | DO_NOT_MIGRATE | Retain source logs as protected evidence; do not seed PID, lock, cache, session, checkpoint or authority files |
| M. DNS/IP/SSL cutover | UNKNOWN | Requires target address, DNS ownership/TTL, certificate and firewall plan |

## Database readiness

The target MariaDB major version is known; source engine/version and compatibility are not. Before migration, capture safe metadata for Vtiger version, table engines, row estimates, database/table charset and collation, SQL mode, triggers, routines, events and view definitions. Preserve the MarvelPBX schema while replacing environment-local view definers with reviewed target identities.

Use a transactionally consistent dump where source engines permit it, including triggers, routines and events. Record dump hash, byte count, start/end time and tool/server versions. Do not migrate the MySQL system database or source accounts. Recreate:

- a least-privilege Vtiger application account;
- a dedicated Vtiger read-only account for Marvel/CEM enrichment;
- administrative migration credentials used only during the window and then revoked or rotated.

After restore, validate schema counts, engine/collation exceptions, `vtiger_crmentity`, users, contacts, tickets, PBXManager totals/statuses, MarvelPBX tables/view, attachment references and orphan counts. Queries used for validation must be read-only.

Rollback is straightforward only while Windows remains frozen. There is no proven bidirectional replication. If Linux accepts writes and rollback is required, preserve the Linux database, quantify the delta and reconcile approved records before reopening Windows; never silently discard or merge two writable histories.

## Files: migrate deliberately

Migrate application code, reviewed custom modules/layouts, Vtiger `storage` attachments, user-uploaded assets required by the application, package assets and reviewed configuration values. Preserve ownership, timestamps where meaningful, hashes and an export manifest.

Do not blindly migrate cache, sessions, compiled templates, temporary files, PID/lock files, stale logs, local sockets, old listener state, authority/health/generation artifacts, CEM checkpoints or journals, raw captures, plaintext secret backups, generated dependency trees from an incompatible platform, or recording bytes that remain managed by UCM/NAS.

## Secrets and credential disposition

| Secret location/type | Disposition |
| --- | --- |
| Vtiger DB settings and application account | Recreate with least privilege; rotate |
| Vtiger `application_unique_key` | Securely preserve for existing encrypted MarvelPBX settings, or rotate only with an explicit re-entry/re-encryption plan |
| Legacy listener DB and AMI credentials | Recreate; rotate where the UCM/DB supports a staged switch |
| UCM HTTPS/API credentials | Recreate or securely transfer, preferably rotate; keep outside source control |
| Read-only CRM password | Recreate and rotate |
| WebSocket bridge auth/origin configuration | Recreate from reviewed values; rotate any key |
| TLS private keys | Prefer reissue; otherwise securely copy only with approved custody and restrictive permissions |
| Observation HMAC salts | Preserve only if cross-host historical correlation is explicitly required; otherwise rotate and start a new evidence scope |
| Authority snapshots, health leases and generation pins | Do not migrate; generate fresh only for a later approved CEM cutover |

Never print secret values in readiness output, shell history, migration manifests or tickets.

## Target service topology

Recommended dependency order:

1. storage/archive mounts where required;
2. MariaDB if local;
3. Apache/PHP and Vtiger scheduled tasks;
4. WebSocket/TCP bridge;
5. legacy AMI listener, authoritative for CRM effects;
6. CEM follower and Event Journal in shadow mode;
7. CRM consumer disabled/non-side-effecting until a separate cutover;
8. optional recording/archive workers after independent validation.

Create separately reviewed systemd units such as `marvelpbx-ws`, `marvelpbx-ami-listener`, `marvelpbx-cem-follower`, `marvelpbx-cem-journal` and `marvelpbx-cem-crm-consumer`, plus timers for bounded scheduled work. Units need explicit users, working directories, dependencies, restart limits, log destinations and hardening. This phase installs none.

## Network readiness

| Source | Destination | Port/protocol | Purpose |
| --- | --- | --- | --- |
| Browser | Linux Apache | 443/TCP, optionally 80 for redirect | Vtiger and same-origin recording proxy |
| Browser | Linux WebSocket bridge | 8080/TCP | Popup client connectivity |
| Legacy/CEM popup runtime | Local approved bridge | 8081/TCP | Popup frames |
| Linux legacy/capture runtime | UCM | 5038/TCP | AMI |
| Linux recording runtime | UCM | 443/TCP | Authenticated recording API/REC transport |
| Linux application/runtime | MariaDB | local socket or 3306/TCP | Vtiger and read-only enrichment |
| Linux host | DNS/NTP/CA services | environment-defined | Stable names, time and trust |

Archive/NAS protocol and ports remain unknown. Validate routes, source-IP allowlists, firewall policy, TLS hostname/chain, time synchronization and WebSocket reverse-proxy behavior without changing the firewall in this phase.

## Production parity checklist

- login, session persistence and role/profile behavior;
- contacts, accounts, tickets, users and attachment retrieval;
- known caller produces one enriched ring popup; unknown caller produces one `(Unknown)` popup without a false match;
- answered and missed-call states match legacy behavior;
- PBXManager row creation, ownership, timestamps and status;
- MarvelPBX list/detail filters and recording availability states;
- known recording plays through same-origin proxy; NOT_FOUND is controlled;
- playback permission works and download is denied by default;
- WebSocket clients reconnect and ports 8080/8081 are healthy;
- queue `6500` / extension `3000` evidence remains a **later CEM pilot check**, not migration ownership;
- authority snapshot defaults to LEGACY, interlock is false, and no migrated health/pin state exists;
- all audit/log output excludes credentials, caller/contact data and physical recording paths.

## Data freeze and outage estimate

CRM users, PBXManager calls, contacts, tickets, settings and attachments can change after the final dump. A controlled maintenance/write freeze is required. Stop source jobs and the source listener in a documented order only at freeze, perform the final DB dump and storage delta sync, and prevent either application from accepting writes until go-live ownership is unambiguous.

Plan a **2–4 hour change window provisionally**, plus a 24-hour observation period. This is not yet a committed outage: a timed rehearsal using measured database/storage sizes must set the final duration. Do not claim zero downtime.

## Recording relationship

Physical UCM/NAS recordings are not part of the application file copy unless evidence shows a locally managed archive. Linux needs resolver settings, a least-privilege API identity, CA chain, network reachability, encryption-key continuity for stored settings and any reviewed archive metadata/mount. Browser playback remains proxy-mediated; no physical path or permanent `recordingurl` backfill is required.

## Non-destructive readiness tool

Run:

```bash
php tools/production_readiness.php \
  --integration-root <integration-root> \
  --vtiger-root <vtiger-root>
```

The tool checks only local versions, PHP modules, expected files, directory access and permission bits. It deliberately does not load config, read credentials, connect to DB/network or write files. `--json` emits safe machine-readable output.

## Blocking gates

1. Complete and approve the Windows source inventory.
2. Measure DB/storage and pass a timed dump/restore/file-sync rehearsal.
3. Validate schema, charset/collation, view definers and Vtiger/customization compatibility.
4. Approve target DNS, TLS, firewall, UCM allowlists and archive connectivity.
5. Build, harden and test Linux service/timer definitions.
6. Create a verified backup set and demonstrate rollback on a clone.
7. Correct overly broad permissions and eliminate stale secret/config backups.
8. Obtain business owner approval for freeze, outage, acceptance and rollback deadlines.