# Vela Deployment and Operations

## Deployment Layout

### NanoPi R6S

```yaml
services:
  ui:
    build: ./apps/vela-ui

  gateway:
    build: ./apps/vela-gateway
    environment:
      OLLAMA_URL: http://nas:11434
      KOKORO_URL: http://nas:8880
      HASS_URL: http://homeassistant:8123
      SEARXNG_URL: http://searxng:8080/search
```

### NAS

```yaml
services:
  ollama:
    image: ollama/ollama

  kokoro:
    image: kokoro-tts
```

## Networking

- all services should be reachable on the internal network
- expected reverse proxy routes:
  - `/` → UI
  - `/api` or `/health` → gateway HTTP routes
  - `/ws` → WebSocket

## Security

- Home Assistant token stored server-side only
- no secrets in the frontend
- internal network isolation preferred
- optional gateway auth can be added later if deployment needs it

## Performance Targets

- wake to response start: under 1.5s
- STT latency: under 800ms
- TTS start latency: under 500ms
- full roundtrip: under 3s

## Key Risks

| Risk | Mitigation |
| --- | --- |
| STT latency on NanoPi | move STT to NAS |
| TTS performance | run TTS on NAS |
| LLM hallucinating actions | enforce strict tool schema |
| WebSocket instability | add heartbeat and reconnect handling |
| Audio sync issues | use chunked streaming and buffering |

## Documentation Maintenance

- update this document when deployment topology, networking, or service placement changes
- keep performance targets and risk mitigations aligned with the current implementation state