Add operations guide with management commands
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>
This commit is contained in:
Cal Corum
parent
197b320b3b
commit
5cd0b5a223
202
OPERATIONS.md
Normal file
202
OPERATIONS.md
Normal file
@ -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]"
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user