From 5cd0b5a223d3feb81725d4d902e4bab717938d71 Mon Sep 17 00:00:00 2001
From: Cal Corum <calcorum@users.noreply.github.com>
Date: Fri, 19 Dec 2025 00:22:21 -0600
Subject: [PATCH] Add operations guide with management commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents:
- systemd service management (start/stop/restart)
- Log viewing with journalctl
- API endpoints and examples
- Configuration via environment variables
- Troubleshooting common issues

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 OPERATIONS.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 202 insertions(+)
 create mode 100644 OPERATIONS.md

diff --git a/OPERATIONS.md b/OPERATIONS.md
new file mode 100644
index 0000000..f4fd297
--- /dev/null
+++ b/OPERATIONS.md
@@ -0,0 +1,202 @@
+# Voice Server Operations Guide
+
+## Service Management
+
+The voice server runs as a user systemd service and auto-starts on boot.
+
+### Status
+
+```bash
+# Check if service is running
+systemctl --user status voice-server
+
+# Check if service is enabled (auto-start)
+systemctl --user is-enabled voice-server
+```
+
+### Start / Stop / Restart
+
+```bash
+# Start the service
+systemctl --user start voice-server
+
+# Stop the service
+systemctl --user stop voice-server
+
+# Restart the service
+systemctl --user restart voice-server
+
+# Reload after config changes (without full restart)
+systemctl --user reload voice-server
+```
+
+### Enable / Disable Auto-Start
+
+```bash
+# Enable auto-start on boot
+systemctl --user enable voice-server
+
+# Disable auto-start
+systemctl --user disable voice-server
+
+# Enable and start immediately
+systemctl --user enable --now voice-server
+```
+
+## Logs
+
+```bash
+# View recent logs
+journalctl --user -u voice-server
+
+# Follow logs in real-time
+journalctl --user -u voice-server -f
+
+# View logs since last boot
+journalctl --user -u voice-server -b
+
+# View last 50 lines
+journalctl --user -u voice-server -n 50
+```
+
+## Health Check
+
+```bash
+# Quick health check
+curl -s http://localhost:8888/health | python3 -m json.tool
+
+# Check specific fields
+curl -s http://localhost:8888/health | jq '.status'
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/notify` | POST | Submit text for TTS playback |
+| `/health` | GET | Health check with system status |
+| `/voices` | GET | List available voice models |
+| `/docs` | GET | Swagger UI documentation |
+
+### Example: Send TTS Request
+
+```bash
+curl -X POST http://localhost:8888/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Hello, this is a test"}'
+```
+
+### Example: Send with Options
+
+```bash
+curl -X POST http://localhost:8888/notify \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "message": "Speaking at a different rate",
+    "rate": 200,
+    "voice": "en_US-lessac-medium"
+  }'
+```
+
+## Configuration
+
+Configuration is via environment variables. Edit the service file or create a `.env` file:
+
+```bash
+# Copy example config
+cp .env.example .env
+
+# Edit configuration
+nano .env
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HOST` | `0.0.0.0` | Bind address |
+| `PORT` | `8888` | Listen port |
+| `MODEL_DIR` | `./models` | Voice model directory |
+| `DEFAULT_VOICE` | `en_US-lessac-medium` | Default voice model |
+| `DEFAULT_RATE` | `170` | Default speech rate (WPM) |
+| `QUEUE_MAX_SIZE` | `50` | Maximum queue size |
+| `LOG_LEVEL` | `INFO` | Logging level |
+
+## Troubleshooting
+
+### Service Won't Start
+
+```bash
+# Check for errors
+journalctl --user -u voice-server -n 100 --no-pager
+
+# Verify paths exist
+ls -la /mnt/NV2/Development/voice-server/.venv/bin/uvicorn
+
+# Test manually
+cd /mnt/NV2/Development/voice-server
+.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8888
+```
+
+### No Audio Output
+
+```bash
+# Check audio devices
+python3 -c "import sounddevice; print(sounddevice.query_devices())"
+
+# Check PulseAudio/PipeWire is running
+pactl info
+
+# Verify PortAudio is installed
+rpm -q portaudio  # Fedora/RHEL
+dpkg -l portaudio19-dev  # Debian/Ubuntu
+```
+
+### Port Already in Use
+
+```bash
+# Find what's using port 8888
+lsof -i :8888
+
+# Kill the process if needed
+kill $(lsof -t -i :8888)
+```
+
+### Voice Model Not Found
+
+```bash
+# List installed models
+ls -la /mnt/NV2/Development/voice-server/models/
+
+# Download a model
+cd /mnt/NV2/Development/voice-server/models/
+curl -LO "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx"
+curl -LO "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json"
+```
+
+## Development
+
+### Run Tests
+
+```bash
+cd /mnt/NV2/Development/voice-server
+.venv/bin/pytest tests/ -v
+```
+
+### Run in Development Mode
+
+```bash
+# Stop the service first
+systemctl --user stop voice-server
+
+# Run with auto-reload
+.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8888
+```
+
+### Update Dependencies
+
+```bash
+cd /mnt/NV2/Development/voice-server
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```