# Canvas Live Integration Setup (Prague T1b)

**Status:** Operational runbook — Ben's in-person checklist
**Date:** 2026-04-20

Canvas is the institutional LMS for the UT Austin side of the Prague
deployment. The CanvasLMSProvider already speaks the real Canvas REST
API; this runbook covers the credentials and env-var setup so every
Axiom node can configure it without editing code.

## Node-operator checklist

1. **Request a Canvas developer key** from UT IT Canvas admin with
   these scopes:
   - `url:GET|/api/v1/users/self` (probe)
   - `url:GET|/api/v1/courses/:course_id/enrollments` (roster sync)
   - `url:POST|/api/v1/courses/:course_id/assignments` (assignment
     creation for checkpoints)
   - `url:PUT|/api/v1/courses/:course_id/assignments/:id/submissions/:user_id` (grade push)

   The developer key is scoped to an OAuth app; Ben generates an API
   token from that app for server-to-server use.

2. **Set env vars** on every Axiom node that talks to Canvas:
   ```bash
   export AXIOM_CANVAS_API_URL="https://utexas.instructure.com"
   export AXIOM_CANVAS_API_TOKEN="..."
   # Optional — override the provider's display name for audit:
   # export AXIOM_LMS_NAME="canvas-utexas"
   # Optional — explicit opt-out at a site (overrides auto-detect):
   # export AXIOM_LMS_PROVIDER=none
   ```

3. **Verify**:
   ```bash
   python -c "
   from axiom.integrations.lms.env import build_lms_provider_from_env
   p = build_lms_provider_from_env()
   print(type(p).__name__, p.available() if p else '<no provider>')
   "
   # Expected: CanvasLMSProvider True
   ```

## Auto-detection precedence

1. ``AXIOM_LMS_PROVIDER=none`` — explicit opt-out. No provider built.
2. ``AXIOM_LMS_PROVIDER`` set to a supported value (currently only
   ``canvas``) — fetch the provider-specific keys.
3. Auto-detect: if both ``AXIOM_CANVAS_API_URL`` AND
   ``AXIOM_CANVAS_API_TOKEN`` are set, ``canvas`` is selected
   without needing ``AXIOM_LMS_PROVIDER``.
4. Otherwise → ``None`` (manual-roster flow, same as
   ``prep lms-setup none``).

Partial Canvas env vars (one set, one missing) → ``None`` silently.
A half-configured node never crashes the chat path.

## Test sandbox

Canvas provides ``test.instructure.com`` for development. Ben can
generate a test token there for integration validation before the
Prague deployment goes live. The same env vars + code path work
unchanged against the sandbox.

## Ordering with P4 walkthrough

``axi classroom prep lms-setup canvas-configure ...`` takes
``--instance-url`` and ``--token`` on the CLI. For scripted /
Docker deployments, the env-var path documented here is the source
of truth; the CLI path is the interactive complement. Both end up
at the same ``CanvasLMSProvider`` with the same config fingerprint.

See also ``docs/working/langfuse-setup.md`` for the tracing
companion runbook.
_Copyright (c) 2026 The University of Texas at Austin and B-Tree Labs. Apache-2.0 licensed._
