# Configuration

The package keeps client-specific runtime values outside Git. Tracked files ending in `.sample` are templates only; they are not active configuration.

Related architecture: MPBX-000 and MPBX-006. This file documents local implementation configuration and does not redefine canonical security or environment-isolation requirements.

## Standard package ports

The reusable package defaults are:

- Asterisk Manager Interface (AMI): `5038`
- Browser WebSocket server: `8080`
- Listener-to-WebSocket TCP bridge: `8081`

The current DEV installation uses the standard WebSocket `8080` and TCP bridge `8081` ports. The previous `8180`/`8181` values were temporary DEV isolation values only and are not package defaults.

## Configuration files

Tracked templates:

- `ami/config/listener_config.inc.php.sample`
- `ws-server/config/server_config.inc.php.sample`

Local runtime files, ignored by Git:

- `ami/config/listener_config.inc.php`
- `ws-server/config/server_config.inc.php`

Create local runtime configuration from the repository root:

```bash
cp ami/config/listener_config.inc.php.sample ami/config/listener_config.inc.php
cp ws-server/config/server_config.inc.php.sample ws-server/config/server_config.inc.php
```

Replace every `CHANGE_ME` with an installation-specific value. Keep `localhost` or `127.0.0.1` only when the corresponding database or bridge genuinely runs on the same host.

Never commit passwords, AMI secrets, authentication keys, client IP addresses, database credentials or populated local runtime configuration. Before sharing a diff, confirm that only `.sample` files contain placeholders.

## CEM and observation configuration inventory

The paths below are repository-relative examples. Local files must remain ignored and should use mode `0600`; directories containing sensitive runtime state should use mode `0700`. Samples contain placeholders only and are never active merely because they are tracked.

| Purpose | Tracked sample | Ignored local file | Sensitive content | Enabled by default |
| --- | --- | --- | --- | --- |
| Sanitized passive AMI capture | `ami/config/ami_capture_config.inc.php.sample` | `ami/config/ami_capture_config.inc.php` | Yes: AMI endpoint, identity and secret | No; capture runs only when explicitly invoked |
| CRM Shadow policy and registries | `config/crm_shadow_config.inc.php.sample` | `config/crm_shadow_config.inc.php` | No active credential should be stored; tenant, queue and extension policy may still be restricted | No; CLI invocation is required and has no CRM side effects |
| CRM parity tolerances and thresholds | `config/crm_parity_config.inc.php.sample` | `config/crm_parity_config.local.php` | No credentials; comparison policy may be operationally restricted | No; parity CLI invocation is required |
| Offline legacy-observation parsing | `config/legacy_observation_offline_config.inc.php.sample` | `config/legacy_observation_offline_config.inc.php` | Contains a salt-file reference and scoped parsing policy, not the salt value | No; offline CLI invocation is required |
| Live legacy-observation hook | `config/legacy_observation_config.inc.php.sample` | `config/legacy_observation_config.inc.php` | Contains a salt-file reference and output/policy settings, not the salt value | **No: `enabled` defaults to `false`** |
| Live-observation HMAC salt | No tracked secret sample | `var/runtime/legacy-observation.salt` or a separately reviewed restrictive local salt file | Yes: local HMAC key material | Not applicable; read only when the live observer is enabled |
| Offline-observation HMAC salt | No tracked secret sample | `var/runtime/legacy-observation-offline.salt` or a separately reviewed restrictive local salt file | Yes: local HMAC key material | Not applicable; read only when offline conversion is invoked |

The CEM follower accepts non-secret source identity directly through `--tenant-id`, `--customer-id`, `--deployment-id`, and `--environment`. Controlled live runs must provide reviewed values; the historical `dev-shadow` defaults exist only for backward compatibility and tests. These identifiers are persisted in follower state to prevent resuming one byte offset under another deployment identity.

Do not place literal HMAC salts in tracked PHP configuration. The live and offline observation tools must coordinate a reviewed salt only when their hashes need to correlate; otherwise use separately scoped salts.

## CEM runtime state and output

The following ignored directories contain generated runtime data rather than configuration:

| Directory | Purpose | Expected protection | Production-enabled by default |
| --- | --- | --- | --- |
| `runtime/ami-capture/` | Sanitized AMI capture JSONL and metadata | Directory `0700`; files `0600`; still treat call metadata as sensitive | No |
| `var/events/` | Append-only canonical CEM JSONL output | Directory `0700`; files `0600` | No |
| `var/runtime/` | Follower checkpoints, locks, aggregate state, salts and observation state/output | Directory `0700`; files `0600` | No |
| `var/runtime/cem-aggregates/` | Active call-aggregate state isolated by capture session | Directory `0700`; files `0600` | No |

The legacy listener remains authoritative for production CRM effects except for a separately reviewed, explicitly interlocked action scope. CEM, Event Journal, Consumer SDK, CRM Shadow and Parity are validated capabilities; the observation hook and real popup adapter remain disabled by default.

## Preflight validation

The preflight tool loads configuration and validates its structure without starting services or opening database or network connections:

```bash
php tools/config_preflight.php
```

By default it checks the two local runtime files. Alternative files can be supplied using options:

```bash
php tools/config_preflight.php \
  --ami ami/config/listener_config.inc.php.sample \
  --ws ws-server/config/server_config.inc.php.sample
```

The equivalent `--option=PATH` form is also supported:

```bash
php tools/config_preflight.php \
  --ami=ami/config/listener_config.inc.php.sample \
  --ws=ws-server/config/server_config.inc.php.sample
```

Positional paths are also accepted:

```bash
php tools/config_preflight.php AMI_CONFIG WS_CONFIG
```

Warnings indicate incomplete client-specific values but do not make an otherwise structurally valid configuration fail. Fatal errors produce a non-zero exit code. The tool reports only whether sensitive groups are populated; it never prints passwords or AMI secrets.

## Service paths

Systemd unit names, users, working directories, PHP paths and repository paths are installation-specific. The current DEV services execute `ami/listener.php` and `ws-server/server.php` directly. The supplied start scripts are package utilities and must not be assumed to be the active systemd execution path.

Any service unit created later must use paths appropriate to its installation. The package must not assume a fixed `<installation-root>` filesystem location.