Server
======

Compose helper inside the **agency-server** repo (also reachable as ``./dev up`` from the umbrella :doc:`workspace`).

Container name resolution
-------------------------

Friendly aliases map to ``agency_*`` container names:

.. list-table::
   :header-rows: 1
   :widths: 24 24

   * - Alias
     - Container
   * - django, wsgi
     - ``agency_django``
   * - asgi
     - ``agency_asgi``
   * - work
     - ``agency_work``
   * - beat
     - ``agency_beat``
   * - flower
     - ``agency_flower``
   * - nginx, web
     - ``agency_nginx``
   * - postgres, db
     - ``agency_postgres``
   * - redis, queue
     - ``agency_redis``
   * - chroma, store
     - ``agency_chroma``
   * - ollama, llm
     - ``agency_ollama``
   * - comfy, comfyui
     - ``agency_comfy``
   * - voice
     - ``agency_voice``

Commands
--------

.. code-block:: bash

   cd agency-server
   ./dev up              # start stack (foreground)
   ./dev down            # stop
   ./dev build           # build images and start
   ./dev enter [svc]     # bash in container (default django)
   ./dev logs [svc]      # follow logs
   ./dev log [svc] [name]# tail file under /usr/src/logs/
   ./dev restart [svc]

Documentation
-------------

.. code-block:: bash

   ./run document        # build Sphinx → static/documentation/

Product URLs (default)
----------------------

- SPA: http://localhost/ (after http://localhost/login/)
- Admin: http://localhost/admin/
- API: http://localhost/api/
- Voice: http://localhost/api/voice/health
- Sphinx HTML: http://localhost/static/documentation/

Voice (STT/TTS)
---------------

Service ``voice`` (``agency_voice``) exposes faster-whisper + Piper.
Nginx strips the prefix: ``/api/voice/stt`` → container ``POST /stt``.

.. code-block:: bash

   cd agency-server
   docker compose build voice
   docker compose up -d voice
   docker compose up -d --force-recreate web   # pick up /api/voice/

Env: ``WHISPER_MODEL``, ``WHISPER_DEVICE`` (``cuda``/``cpu``), ``PIPER_VOICE``.
Models cache in volume ``agency_voice``. Details: ``context/voice/README.md``.

Agent chat (``AgencyAgentTest``) uses mic → STT and optional auto-speak TTS
when ``/api/voice/health`` is OK.

ComfyUI (image gen)
-------------------

Service ``comfy`` (``agency_comfy``) is local GPU txt2img. Django uses
``COMFYUI_URL`` (``http://comfy:8188``). Host UI: http://127.0.0.1:8188

.. code-block:: bash

   cd agency-server
   docker compose build comfy
   docker compose up -d comfy

First boot downloads SD 1.5 fp16 (~2 GB) into volume ``agency_comfy``.
Default ``--lowvram`` so it can share the GPU with Ollama. Details:
``context/comfyui/README.md``.

Compose file and env templates live in **agency-server** root. Package source is mounted from sibling **agency-django**.

Stack topology and services: :doc:`../framework/deployment`.