companion/@deployments/nginx/README.md

# @companion nginx configuration

## Installation

```bash
# Generate wildcard cert (one-time):
mkcert -install
mkcert -cert-file /etc/nginx/certs/local/_wildcard.quinn.apricot.local+1.pem \
       -key-file /etc/nginx/certs/local/_wildcard.quinn.apricot.local+1-key.pem \
       "*.quinn.apricot.local" quinn.apricot.local

# Add to /etc/hosts (if not already present):
echo "127.0.0.1 ai.quinn.apricot.local" | sudo tee -a /etc/hosts

# Symlink into nginx sites-enabled:
sudo ln -sf "$(pwd)/ai.quinn.apricot.local.conf" /etc/nginx/sites-enabled/ai.quinn.apricot.local.conf

# Remove old config if present:
sudo rm -f /etc/nginx/sites-enabled/companion.lilith.apricot.local.conf

# Verify config and reload:
sudo nginx -t && sudo systemctl reload nginx
```

## Domain

| Domain | Upstream | Port |
|--------|----------|------|
| `ai.quinn.apricot.local` | companion-api (NestJS) + companion-web (Vite) | 3850 / 5850 |

Single domain mirrors production (`ai.transquinnftw.com`). API paths (`/voice/`, `/chat`, `/session`, `/health`, `/api/`) route to companion-api on :3850. Everything else routes to the Vite dev server on :5850.

## SSL Certificates

Uses wildcard cert for `*.quinn.apricot.local`:

```
/etc/nginx/certs/local/_wildcard.quinn.apricot.local+1.pem
/etc/nginx/certs/local/_wildcard.quinn.apricot.local+1-key.pem
```

## Voice WebSocket Notes

- `proxy_buffering off` is mandatory for the `/voice/` location
- PCM binary frames must not be buffered — any buffering causes audio glitches
- `proxy_read_timeout 3600s` supports 1-hour voice sessions
- The `$connection_upgrade` map must be in the nginx `http` context (nginx.conf)