@spectrumsense/spectrum-chat-dev/examples/DEPLOYMENT.md

Embeddable AI Widget - Add trusted, evidence-based answers directly to your website. Simple installation, enterprise-grade security.

# Spectrum Chat - Deployment Guide

This guide explains how to deploy the Spectrum Chat widget with different API endpoints for various environments.

## 🎯 **Environment Configuration**

The widget uses a configuration system that automatically detects the environment and sets the appropriate API endpoint.

### **Configuration Files**

- `config.js` - Base configuration with auto-detection
- `config.local.js` - Local environment override
- `config.develop.js` - Develop environment override  
- `config.prod.js` - Prod environment override

## 🚀 **Deployment Options**

### **Option 1: Auto-Detection (Recommended)**

The base `config.js` automatically detects the environment based on the hostname:

```html
<!-- Include base configuration -->
<script src="config.js"></script>
<script src="../dist/spectrum-chat.js"></script>
```

**Auto-detection rules:**
- `localhost` or `127.0.0.1` → Local (`http://localhost:8000`)
- Hostname contains `dev` or `develop` → Develop (`https://dev-api.spectrumsense.co`)
- All other hostnames → Prod (`https://api.spectrumsense.co`)

### **Option 2: Manual Environment Override**

For specific environments, include the appropriate config file:

```html
<!-- Local -->
<script src="config.js"></script>
<script src="config.local.js"></script>
<script src="../dist/spectrum-chat.js"></script>

<!-- Develop -->
<script src="config.js"></script>
<script src="config.develop.js"></script>
<script src="../dist/spectrum-chat.js"></script>

<!-- Prod -->
<script src="config.js"></script>
<script src="config.prod.js"></script>
<script src="../dist/spectrum-chat.js"></script>
```

### **Option 3: URL Parameter Override**

You can also override the API endpoint via URL parameters:

```html
<!-- Example: ?api_root=https://custom-api.example.com -->
<script>
  // Override API root from URL parameter
  const urlParams = new URLSearchParams(window.location.search);
  const apiRoot = urlParams.get('api_root');
  if (apiRoot) {
    window.SpectrumConfig.overrideConfig({ API_ROOT: apiRoot });
  }
</script>
<script src="config.js"></script>
<script src="../dist/spectrum-chat.js"></script>
```

## 🔧 **Customizing API Endpoints**

### **For Local**
Edit `config.local.js`:
```javascript
window.SpectrumConfig.overrideConfig({
  API_ROOT: 'http://localhost:8000',  // Your local API
  // ... other settings
});
```

### **For Develop**
Edit `config.develop.js`:
```javascript
window.SpectrumConfig.overrideConfig({
  API_ROOT: 'https://dev-api.spectrumsense.co',  // Your develop API
  // ... other settings
});
```

### **For Prod**
Edit `config.prod.js`:
```javascript
window.SpectrumConfig.overrideConfig({
  API_ROOT: 'https://api.spectrumsense.co',  // Your prod API
  // ... other settings
});
```

## 📁 **File Structure**

```
examples/
├── config.js                 # Base configuration with auto-detection
├── config.local.js           # Local overrides
├── config.develop.js         # Develop overrides
├── config.prod.js            # Prod overrides
├── real/
│   ├── plain-html-example.html    # Uses config.js
│   ├── template-base.html         # Uses config.js
│   └── template-home.html         # Uses config.js
└── DEPLOYMENT.md             # This file
```

## 🌐 **Deployment Examples**

### **Local Development**
```bash
# Start local dev server
python -m http.server 3000

# Access: http://localhost:3000/examples/real/plain-html-example.html
# API will automatically point to: http://localhost:8000
```

### **Develop Deployment**
```bash
# Deploy to develop server
# Hostname: dev.spectrumsense.co
# API will automatically point to: https://dev-api.spectrumsense.co
```

### **Prod Deployment**
```bash
# Deploy to prod server
# Hostname: spectrumsense.co
# API will automatically point to: https://api.spectrumsense.co
```

## 🔍 **Debugging Configuration**

The configuration system logs the current settings to the console:

```javascript
// Check current configuration
console.log('Current config:', window.SpectrumConfig.getConfig());
console.log('API Root:', window.SpectrumConfig.getApiRoot());
console.log('Environment:', window.SpectrumConfig.getEnvironment());
```

## ⚡ **Quick Start**

1. **For local development**: Just use the examples as-is
2. **For develop**: Deploy with develop hostname or include `config.develop.js`
3. **For prod**: Deploy with prod hostname or include `config.prod.js`

The auto-detection system handles most cases automatically!

## 🛠️ **Advanced Configuration**

### **Custom Environment Detection**
```javascript
// Override environment detection
window.SpectrumConfig.overrideConfig({
  ENVIRONMENT: 'custom',
  API_ROOT: 'https://custom-api.example.com'
});
```

### **Runtime Configuration Change**
```javascript
// Change API endpoint at runtime
window.SpectrumConfig.overrideConfig({
  API_ROOT: 'https://new-api.example.com'
});
```

This configuration system provides maximum flexibility while maintaining simplicity for common deployment scenarios.