hope-voice-api/docs/DEPLOYMENT.md

NAS deployment — 2026-09-08

Historical deployment record, not a current health assertion. The iOS music player was removed September 12; the media/AAC details below concern the retained backend, not a current iOS feature. Reinspect server state before making deployment changes.

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. The backend compatibility source was not pushed during that deployment; recheck the sibling repository before acting. An iOS push does not publish it. Future backend CI deployments must include the compatibility patch to preserve it.