# V-Connect PBX — Deployment Profiles

How V-Connect is deployed in the field. The golden master image is cloned per
site; `scripts/pbx-setup-client.sh` then tailors the box. Two profiles cover
essentially all installs.

---

## 1. On-Premise PBX — ~90% of installations

A Debian box (physical, or a local VM) living at the customer site.

- **Prep stage:** starts on **DHCP** for staging/imaging on the bench.
- **On site:** assigned a **dedicated static LAN IP** so desk phones register to it.
  - Set with NetworkManager: `nmcli connection modify "<conn>" ipv4.method manual
    ipv4.addresses <ip>/24 ipv4.gateway <gw> ipv4.dns "<dns>"` then down/up.
  - After an IP change, update `APP_URL` + `SIP_REALM` in `.env` (+ `config:cache`)
    and `local_net` in `pjsip.conf`. `external_*_address` stays UNSET on a pure
    LAN box (Asterisk uses the live interface IP — survives IP changes).
- **Internet breakout on the box:** the box has outbound internet at the site
  (needed for the SIP trunk, updates, voicemail/recording email, and NTP time).
  Until breakout exists, internal calling works but trunk/updates/email/DNS/NTP
  do not.

### 1a. Desk-phones-only (no webphone / no mobile) — the common case
- Install with **LAN mode**:
  `sudo bash /var/www/html/scripts/pbx-setup-client.sh --lan-mode`
- HTTP GUI on the LAN IP, **no SSL**, no WSS/webphone, no mobile TLS transport.

### 1b. Webphones / mobile app required
- The site's **fibre provides a static PUBLIC IP** that is forwarded to the PBX
  (for WSS/TLS breakout).
- Install in **full mode** (NO `--lan-mode`) with a **public hostname +
  Let's Encrypt cert**, so WebRTC (browser webphone) and the mobile TLS transport
  work. `external_*_address` here is the public/WAN IP.

---

## 2. Data-Centre VM — hosted

- Spin the software up on a VM in our data centre.
- **Full mode** (standard `pbx-setup-client.sh`): public hostname + Let's Encrypt
  SSL. Webphone + mobile available. This is what the master/dev box itself runs.

---

## Setup-command mapping

| Scenario | Command |
|---|---|
| On-prem, desk phones only | `pbx-setup-client.sh --lan-mode` |
| On-prem, webphones/mobile (public IP) | `pbx-setup-client.sh` (full) |
| Data-centre VM | `pbx-setup-client.sh` (full) |

Both profiles share the same first-run steps: clone from the golden image →
setup regenerates SSH host keys + machine-id (unique per appliance), rewrites
`.env`, factory-resets the DB, and (on typed `yes`) purges the previous
client's recordings/voicemail/logs/backups.

---

## Edge case: non-standard web ports (rare — do it per-site)

Some sites can't give us 80/443 on their public IP (already used by another
service). IT then forwards alternative ports. This is rare, so we handle it
**manually on that box** rather than in the setup script. Touch points:

1. **GUI / webphone URL** — must reflect the port the *outside world* connects on:
   - `.env`: `APP_URL=https://<host>:<port>` and `WEBRTC_WSS_URL=wss://<host>:<port>/ws`
   - then `php artisan config:cache`.
2. **Apache** — only if the forward is *port-preserving* (external 8443 →
   internal 8443). Add `Listen <port>` and change the vhost to `*:<port>`. If the
   forward *translates* (external 8443 → internal 443), leave Apache on 443.
3. **Firewall** — open the internal port(s) Apache listens on (edit the nftables
   web-ports line in `app/Console/Commands/PbxDeploy.php` for that box, or add a
   rule via the GUI/DB, then re-apply).
4. **Certificate** — the Let's Encrypt **HTTP-01 challenge always uses port 80**
   from the internet; it is NOT configurable. If port 80 can't reach the PBX:
   - use **DNS-01** (`certbot certonly --manual --preferred-challenges dns ...`,
     add the TXT record), or
   - **import** a cert the customer/IT provides into the HTTPS vhost paths, or
   - self-signed (fine for desk phones; webphones over WSS will reject it).

SIP/RTP ports (5060/5061/8089 + RTP 10000-40000) are independent of the web
ports and forwarded separately for trunks/webphone media.