# Deployment Guide

This guide explains how to deploy aitherboard with Piper TTS on a remote server with Apache.

## Architecture

```
Internet → Apache (443) → aitherboard container (9876)
                              ↓
                         piper-tts container (10200, internal)
```

- **Apache** proxies HTTP/WebSocket requests to the aitherboard container
- **aitherboard** container connects to **piper-tts** container via Docker internal networking
- **piper-tts** is not exposed to the host - only accessible from within Docker network

## Docker Compose Setup

The `docker-compose.yml` is ready to use as-is. It:

1. Creates a Docker network (`aitherboard-network`) for container communication
2. Exposes aitherboard on port `9876` (for Apache to proxy to)
3. Keeps piper-tts internal (port `10200` only accessible from Docker network)
4. Uses service names (`piper-tts`) for internal communication

## Apache Configuration

Your Apache configuration should proxy to `localhost:9876` (where aitherboard runs):

```apache
ProxyPreserveHost On
ProxyRequests Off

# WebSocket upgrade handling - CRITICAL for Nostr apps
RewriteEngine On
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule ^/?(.*) "ws://127.0.0.1:9876/$1" [P,L]

# Regular HTTP proxy for static files and API calls (catch-all - MUST come LAST)
ProxyPass / http://127.0.0.1:9876/
ProxyPassReverse / http://127.0.0.1:9876/

# Headers for WebSocket compatibility
ProxyAddHeaders On
Header always set X-Forwarded-Proto "https"
Header always set X-Forwarded-Port "443"
```

**Important**: Apache only needs to proxy to aitherboard. It does NOT need to route to piper-tts - that's handled internally by Docker.

## Deployment Steps

1. **Clone and prepare the repository:**
   ```bash
   git clone <your-repo>
   cd aitherboard
   ```

2. **Set up Wyoming Piper:**
   ```bash
   ./setup-wyoming-piper.sh
   ```

3. **Download voices (optional, but recommended):**
   ```bash
   ./download-voices.sh
   ```

4. **Start the containers:**
   ```bash
   docker-compose up -d --build
   ```

5. **Verify containers are running:**
   ```bash
   docker-compose ps
   ```

6. **Check logs if needed:**
   ```bash
   docker-compose logs aitherboard
   docker-compose logs piper-tts
   ```

## Container Communication

The aitherboard container connects to piper-tts using:

- **Hostname**: `piper-tts` (Docker service name)
- **Port**: `10200` (internal Docker network)

This is configured via environment variables in `docker-compose.yml`:
- `PIPER_TTS_HOST=piper-tts`
- `PIPER_TTS_PORT=10200`

You can override these if needed, but the defaults work for Docker Compose.

## Network Flow

1. **User request** → Apache (port 443)
2. **Apache** → aitherboard container (localhost:9876)
3. **aitherboard** → piper-tts container (piper-tts:10200 via Docker network)
4. **piper-tts** → returns audio to aitherboard
5. **aitherboard** → returns audio to Apache
6. **Apache** → returns audio to user

## Troubleshooting

### Piper TTS not working

1. **Check if containers are on the same network:**
   ```bash
   docker network inspect aitherboard_aitherboard-network
   ```

2. **Test connection from aitherboard to piper-tts:**
   ```bash
   docker exec aitherboard ping piper-tts
   ```

3. **Check piper-tts logs:**
   ```bash
   docker-compose logs piper-tts
   ```

4. **Verify voices are available:**
   ```bash
   docker exec piper-tts ls -la /data/voices/
   ```

### Apache can't connect to aitherboard

1. **Check if aitherboard is listening:**
   ```bash
   curl http://localhost:9876/healthz.json
   ```

2. **Check aitherboard logs:**
   ```bash
   docker-compose logs aitherboard
   ```

3. **Verify port mapping:**
   ```bash
   docker-compose ps
   # Should show: 0.0.0.0:9876->9876/tcp
   ```

## Environment Variables

You can customize the setup via environment variables in `docker-compose.yml`:

- `PIPER_TTS_HOST`: Override Piper hostname (default: `piper-tts`)
- `PIPER_TTS_PORT`: Override Piper port (default: `10200`)
- `NODE_ENV`: Set to `production` (already set)

## Security Notes

- **piper-tts** is NOT exposed to the internet - only accessible from Docker network
- Only **aitherboard** port `9876` is exposed to the host
- Apache handles SSL/TLS termination
- All internal communication happens over Docker's bridge network

## Updating

To update the containers:

```bash
docker-compose pull  # If using pre-built images
docker-compose up -d --build  # Rebuild and restart
```

To update voices:

```bash
./download-voices.sh
docker-compose restart piper-tts  # Restart to pick up new voices
```