# New Client Setup Guide

Complete steps to bring a fresh V-Connect PBX online for a new client,
starting from a cloned VM image.

---

## Prerequisites

Before you start:

- [ ] New VM is booted and you can SSH in as root
- [ ] A DNS A record for the client's hostname points to the VM's public IP
  (e.g. `pbx.clientname.com → 196.25.10.50`)
- [ ] Port 80 and 443 are open (needed for Let's Encrypt SSL)
- [ ] You have access to Bitbucket: https://bitbucket.org/openvdev/vconnectpbx

---

## Step 1 — Connect to Bitbucket (one-time per machine)

The cloned image has the code but isn't connected to git yet.
You need a read-only deploy key so the machine can pull future updates.

### 1a. Generate an SSH key on the new VM

```bash
ssh-keygen -t ed25519 -C "vconnect-client-CLIENTNAME" -f /root/.ssh/bitbucket_pbx -N ""
cat /root/.ssh/bitbucket_pbx.pub
```

Copy the output (starts with `ssh-ed25519 ...`).

### 1b. Add the key to Bitbucket

1. Go to: https://bitbucket.org/openvdev/vconnectpbx/admin/access-keys/
2. Click **Add key**
3. Label: `client-CLIENTNAME`
4. Paste the public key
5. Click **Add SSH key**

> This is a **read-only** deploy key — the client machine can pull but never push.

### 1c. Configure SSH on the VM

```bash
cat > /root/.ssh/config << 'EOF'
Host bitbucket.org
    HostName bitbucket.org
    User git
    IdentityFile /root/.ssh/bitbucket_pbx
    IdentitiesOnly yes
EOF
chmod 600 /root/.ssh/config
```

### 1d. Test the connection

```bash
ssh -T git@bitbucket.org
# Expected: "authenticated via ssh key. You can use git to connect to Bitbucket."
```

### 1e. Connect the repo and pull latest code

```bash
git config --global --add safe.directory /var/www/html
git -C /var/www/html init
git -C /var/www/html remote add origin git@bitbucket.org:openvdev/vconnectpbx.git
git -C /var/www/html fetch origin
git -C /var/www/html reset --hard origin/main
```

---

## Step 2 — Run the setup script

This single script handles everything: hostname, `.env`, SSL certificate,
Apache, Asterisk, database reset, and deployment.

```bash
sudo bash /var/www/html/scripts/pbx-setup-client.sh
```

### What it asks

| Prompt | Example | Notes |
|---|---|---|
| Company name | `Acme Corp` | Used in email subjects and GUI title |
| PBX hostname | `pbx.acme.com` | DNS must already point here |
| Server public IP | `196.25.10.50` | Auto-detected, press Enter to confirm |
| Admin email | `admin@pbx.acme.com` | Used for SSL cert registration |
| Mail from address | `pbx@pbx.acme.com` | Sender address for voicemail/alerts |
| DB password | *(leave blank)* | Auto-generates a strong random password |
| AMI password | *(leave blank)* | Auto-generates a strong random password |
| SMTP host | `smtp.socketlabs.com` | Press Enter for default |
| SMTP port | `587` | Press Enter for default |
| SMTP password | *(leave blank)* | Press Enter to use OpenV default account |
| Wipe database? | `Y` | Always Y on a clone — clears previous client data |

### What it does automatically

1. Sets machine hostname (e.g. `pbx-acme`)
2. Installs PHP dependencies (`composer install`)
3. Writes `/var/www/html/.env` with all client values
4. Updates MariaDB `asterisk` user password
5. Updates Asterisk AMI password in `manager.conf`
6. Writes Apache HTTP + HTTPS vhosts
7. Obtains Let's Encrypt SSL certificate (falls back to self-signed if DNS not ready)
8. Updates `pjsip.conf` with the new public IP
9. Reloads Apache + Asterisk
10. Factory reset — wipes all previous client data, seeds fresh admin login
11. Fixes file permissions
12. Runs `pbx:deploy` (firewall, cron, sudoers, BLF hints, etc.)

---

## Step 3 — First login

Open a browser and go to `https://pbx.acme.com`

```
Email:    admin@example.com
Password: 0penV70penV7
```

**Change the admin password immediately** (top-right menu → Profile).

---

## Step 4 — Configure the PBX

Work through these in order:

1. **Settings → System** — set timezone, company name, WebRTC settings
2. **Trunks → SIP Trunks** — add the client's SIP trunk (ECN or other carrier)
3. **Trunks → Outbound Routes** — add outbound dial patterns
4. **Trunks → Inbound Routes** — add DIDs and point them to extensions/IVR/queue
5. **Extensions** — create extensions, set passwords, assign devices
6. **Applications → IVR** — configure auto-attendant if needed
7. **Call Center → Queues** — set up call queues if needed

---

## Step 5 — Verify health

Go to **Settings → System Health** and confirm all checks are green.

Expected on a fresh system (before extensions/routes are added):
- ⚠ Warning — DID Normalizer (no routes yet)
- ⚠ Warning — Extension Dialplans (no extensions yet)
- ⚠ Warning — Recording (no extensions yet)
- ⚠ Warning — Inbound Routes (no routes yet)
- ⚠ Warning — Asterisk trunk (no trunk registered yet)

These will turn green as you configure the system.

---

## SSL Certificate Notes

If Let's Encrypt fails during setup (DNS not propagated yet):
- The script falls back to a self-signed certificate
- The GUI will show a browser security warning — this is safe to bypass for initial setup
- Once DNS is confirmed, re-run certbot manually:

```bash
certbot certonly --webroot -w /var/www/html/public -d pbx.acme.com
systemctl reload apache2
```

---

## Troubleshooting

### 500 Server Error on first load

```bash
cd /var/www/html
composer install --no-dev --optimize-autoloader
php artisan key:generate --force
chown -R www-data:www-data storage bootstrap/cache vendor
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan cache:clear
```

### Factory reset didn't run

```bash
sudo php /var/www/html/scripts/php/factory-reset.php --yes-i-am-sure
```

### Asterisk not responding

```bash
systemctl status asterisk
systemctl restart asterisk
```

### Apache config error

```bash
apache2ctl configtest
systemctl status apache2
```