view release on metacpan or  search on metacpan

docs/web_service.md  view on Meta::CPAN

# Install SDK
RUN pip install signalwire-agents

# Copy static files
COPY ./static /app/static
COPY ./web_config.json /app/web_config.json

# Expose port
EXPOSE 8002

# Run WebService
CMD ["python", "-c", "from signalwire_agents import WebService; WebService(config_file='web_config.json').start()"]
```

### Systemd Service

Create `/etc/systemd/system/signalwire-web.service`:

```ini
[Unit]
Description=SignalWire Web Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/signalwire
Environment="SWML_SSL_CERT=/etc/ssl/certs/server.crt"
Environment="SWML_SSL_KEY=/etc/ssl/private/server.key"
ExecStart=/usr/bin/python3 -c "from signalwire_agents import WebService; WebService(directories={'/': '/var/www/html'}).start()"
Restart=always

[Install]
WantedBy=multi-user.target
```

### Nginx Reverse Proxy

For production, use Nginx as a reverse proxy:

```nginx
server {
    listen 80;
    server_name static.example.com;
    
    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name static.example.com;
    
    ssl_certificate /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;
    
    location / {
        proxy_pass http://localhost:8002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Cache static assets
        location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
            proxy_pass http://localhost:8002;
            expires 1h;
            add_header Cache-Control "public, immutable";
        }
    }
}
```

## Best Practices

### Security
1. **Always use HTTPS in production** - Protect data in transit
2. **Change default credentials** - Never use auto-generated auth in production
3. **Restrict file types** - Use `allowed_extensions` to whitelist safe files
4. **Disable directory browsing** - Turn off in production environments
5. **Use reverse proxy** - Put Nginx/Apache in front for additional security

### Performance
1. **Set appropriate cache headers** - WebService adds 1-hour cache by default
2. **Limit file sizes** - Adjust `max_file_size` based on your needs
3. **Use CDN for static assets** - Offload traffic for better performance
4. **Compress large files** - Use gzip/brotli at reverse proxy level

### Organization
1. **Separate content types** - Use different routes for different file types
2. **Version your assets** - Include version in path (e.g., `/assets/v1/`)
3. **Use index.html** - Provide default files for directories
4. **Document your structure** - Maintain clear directory organization

## Troubleshooting

### Common Issues

**Issue: "FastAPI not available"**
```bash
# Install FastAPI and uvicorn
pip install fastapi uvicorn
```

**Issue: SSL certificate errors**
```python
# Check certificate paths
import os
print(os.path.exists("/path/to/cert.pem"))  # Should be True
print(os.path.exists("/path/to/key.pem"))   # Should be True
```

**Issue: Permission denied**
```bash
# Ensure read permissions on directories
chmod -R 755 /path/to/static/files
```

**Issue: Directory not found**
```python
# Use absolute paths