4.5 KiB

Raw Blame History

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:

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

Apache Configuration

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

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

Clone and prepare the repository:
```
git clone <your-repo>
cd aitherboard
```
Set up Wyoming Piper:
```
./setup-wyoming-piper.sh
```
Download voices (optional, but recommended):
```
./download-voices.sh
```
Start the containers:
```
docker-compose up -d --build
```
Verify containers are running:
```
docker-compose ps
```

Check logs if needed:

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

User request → Apache (port 443)
Apache → aitherboard container (localhost:9876)
aitherboard → piper-tts container (piper-tts:10200 via Docker network)
piper-tts → returns audio to aitherboard
aitherboard → returns audio to Apache
Apache → returns audio to user

Troubleshooting

Piper TTS not working

Check if containers are on the same network:

docker network inspect aitherboard_aitherboard-network

Test connection from aitherboard to piper-tts:
```
docker exec aitherboard ping piper-tts
```
Check piper-tts logs:
```
docker-compose logs piper-tts
```

Verify voices are available:

docker exec piper-tts ls -la /data/voices/

Apache can't connect to aitherboard

Check if aitherboard is listening:

curl http://localhost:9876/healthz.json

Check aitherboard logs:
```
docker-compose logs aitherboard
```

Verify port mapping:

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:

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

To update voices:

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

4.5 KiB Raw Blame History