hope-voice-api/docs/DEPLOYMENT.md

NAS deployment — 2026-09-08

The voice container on 192.168.86.2 hosts LiveKit, the voice agent, token service, music API and nginx. The app connects to https://192.168.86.2:9178. Docker uses host networking and an unless-stopped restart policy.

• Image: hope-voice-api-voice:68f4c46-ios-audio.
• LLM: qwen2.5-vl-3b, through OpenWebUI at http://192.168.86.2:3005/api.
• Speech: existing Azure configuration, unchanged.
• Persistent certs, skills and music: /mnt/user/dev/hope-voice-api mounts.
• Build source: /mnt/user/dev/hope-voice-deploy-68f4c46, a separate clean archive plus the iOS audio compatibility patch. The pre-existing dirty backend checkout was not overwritten.
• Local compatibility source: sibling hope-voice-api/web/media_server.py; regression test: hope-voice-api/tests/test_ios_audio.py.

The music service retains original WebM files. An explicit ?format=m4a request generates and caches AAC audio under media/files/ios, serving byte ranges for iOS playback and seeking. Browser requests remain unchanged.

Health and rollback

ssh [email protected] 'docker inspect --format "{{.State.Status}} {{.State.Health.Status}}" voice'

The stopped container voice-before-ios-audio retains the baseline deployment. If rollback is needed, first inspect both containers, then stop the current voice, rename it to a unique recovery name, rename voice-before-ios-audio to voice, and start it. This restores the baseline without deleting images, containers or the music library; it does not include iOS AAC conversion.

scripts/deploy-backend.sh records the launch configuration and refuses to replace an existing voice container. Run it on the NAS only after building the named image and explicitly handling the existing container. It reads credentials on the NAS and never prints them. No source changes were pushed; future CI deployments must include the compatibility patch to preserve it.