aitherboard/DEPLOYMENT.md

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):

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:

   git clone <your-repo>
   cd aitherboard
   

2. Set up Wyoming Piper:

   ./setup-wyoming-piper.sh
   

3. Download voices (optional, but recommended):

   ./download-voices.sh
   

4. Start the containers:

   docker-compose up -d --build
   

5. Verify containers are running:

   docker-compose ps
   

6. 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

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:

   docker network inspect aitherboard_aitherboard-network
   

2. Test connection from aitherboard to piper-tts:

   docker exec aitherboard ping piper-tts
   

3. Check piper-tts logs:

   docker-compose logs piper-tts
   

4. Verify voices are available:

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

Apache can't connect to aitherboard

1. Check if aitherboard is listening:

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

2. Check aitherboard logs:

   docker-compose logs aitherboard
   

3. 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