feat(docs): refresh deployment page

This commit is contained in:
Musa 2025-12-23 12:39:21 -08:00
parent a381bd46bb
commit 217048fabc

View file

@ -3,17 +3,17 @@
Deployment
==========
This guide shows how to deploy Plano directly using Docker without the archgw CLI, including basic runtime checks for routing and health monitoring.
This guide shows how to deploy Plano directly using Docker without the ``plano`` CLI, including basic runtime checks for routing and health monitoring.
Docker Deployment
-----------------
Below is a minimal, production-ready example showing how to deploy the Plano Docker image directly and run basic runtime checks. Adjust image names, tags, and the ``arch_config.yaml`` path to match your environment.
Below is a minimal, production-ready example showing how to deploy the Plano Docker image directly and run basic runtime checks. Adjust image names, tags, and the ``plano_config.yaml`` path to match your environment.
.. note::
You will need to pass all required environment variables that are referenced in your ``arch_config.yaml`` file.
You will need to pass all required environment variables that are referenced in your ``plano_config.yaml`` file.
For ``arch_config.yaml``, you can use any sample configuration defined earlier in the documentation. For example, you can try the :ref:`LLM Routing <llm_router>` sample config.
For ``plano_config.yaml``, you can use any sample configuration defined earlier in the documentation. For example, you can try the :ref:`LLM Routing <llm_router>` sample config.
Docker Compose Setup
~~~~~~~~~~~~~~~~~~~~
@ -24,14 +24,14 @@ Create a ``docker-compose.yml`` file with the following configuration:
# docker-compose.yml
services:
archgw:
image: katanemo/archgw:0.3.22
container_name: archgw
plano:
image: katanemo/plano:0.4.0
container_name: plano
ports:
- "10000:10000" # ingress (client -> arch)
- "12000:12000" # egress (arch -> upstream/llm proxy)
- "10000:10000" # ingress (client -> plano)
- "12000:12000" # egress (plano -> upstream/llm proxy)
volumes:
- ./arch_config.yaml:/app/arch_config.yaml:ro
- ./plano_config.yaml:/app/plano_config.yaml:ro
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY:?error}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:?error}
@ -39,7 +39,7 @@ Create a ``docker-compose.yml`` file with the following configuration:
Starting the Stack
~~~~~~~~~~~~~~~~~~
Start the services from the directory containing ``docker-compose.yml`` and ``arch_config.yaml``:
Start the services from the directory containing ``docker-compose.yml`` and ``plano_config.yaml``:
.. code-block:: bash
@ -51,7 +51,7 @@ Check container health and logs:
.. code-block:: bash
docker compose ps
docker compose logs -f archgw
docker compose logs -f plano
Runtime Tests
-------------
@ -74,7 +74,7 @@ Expected output:
.. code-block:: json
"gpt-4o-2024-08-06"
"gpt-5.2"
Model-Based Routing
~~~~~~~~~~~~~~~~~~~
@ -84,14 +84,14 @@ Test explicit provider and model routing:
.. code-block:: bash
curl -s -H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Explain quantum computing"}], "model":"anthropic/claude-3-5-sonnet-20241022"}' \
-d '{"messages":[{"role":"user","content":"Explain quantum computing"}], "model":"anthropic/claude-sonnet-4-5"}' \
http://localhost:12000/v1/chat/completions | jq .model
Expected output:
.. code-block:: json
"claude-3-5-sonnet-20241022"
"claude-sonnet-4-5"
Troubleshooting
---------------
@ -100,19 +100,19 @@ Common Issues and Solutions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Environment Variables**
Ensure all environment variables (``OPENAI_API_KEY``, ``ANTHROPIC_API_KEY``, etc.) used by ``arch_config.yaml`` are set before starting services.
Ensure all environment variables (``OPENAI_API_KEY``, ``ANTHROPIC_API_KEY``, etc.) used by ``plano_config.yaml`` are set before starting services.
**TLS/Connection Errors**
If you encounter TLS or connection errors to upstream providers:
- Check DNS resolution
- Verify proxy settings
- Confirm correct protocol and port in your ``arch_config`` endpoints
- Confirm correct protocol and port in your ``plano_config`` endpoints
**Verbose Logging**
To enable more detailed logs for debugging:
- Run archgw with a higher component log level
- Run plano with a higher component log level
- See the :ref:`Observability <observability>` guide for logging and monitoring details
- Rebuild the image if required with updated log configuration