.. _backend_configuration:

Open edX Backend: configuration
===============================

.. contents:: On this page
   :local:
   :depth: 2

The backend is configured through **Django settings** on the LMS. In a normal Open edX
deployment these are supplied by the
`Panorama Tutor plugin <https://github.com/aulasneo/tutor-contrib-panorama>`_; this page
documents what each setting does so you understand what the plugin sets and can troubleshoot.

Settings reference
------------------

.. list-table::
   :header-rows: 1
   :widths: 34 66

   * - Setting
     - Purpose
   * - ``PANORAMA_MODE``
     - One of ``DEMO``, ``FREE``, ``SAAS``, ``CUSTOM``. Defaults to ``DEMO`` when unset. See
       :ref:`backend_modes`.
   * - ``PANORAMA_AWS_ACCESS_KEY``
     - AWS access key used to call QuickSight (``CUSTOM``) and to sign requests to the
       Panorama API (``FREE`` / ``SAAS``).
   * - ``PANORAMA_AWS_SECRET_ACCESS_KEY``
     - Secret for the access key above.
   * - ``PANORAMA_AWS_ACCOUNT_ID``
     - AWS account ID that owns the QuickSight dashboards (``CUSTOM``).
   * - ``PANORAMA_REGION``
     - AWS region of the QuickSight deployment.
   * - ``PANORAMA_DEFAULT_USER_ARN``
     - QuickSight user ARN used when a user has no explicit ARN in their access configuration.
   * - ``PANORAMA_ENABLE_STUDENT_VIEW``
     - When true, users without an explicit configuration get the student dashboards (see
       :ref:`backend_modes`).
   * - ``LMS_BASE``
     - The LMS base domain. Used to build the QuickSight ``AllowedDomains`` and as the ``lms``
       parameter passed to student dashboards.
   * - ``HTTPS``
     - Must be ``'on'``. The API refuses to serve dashboards over plain HTTP (it returns HTTP
       421). Panorama is only supported from HTTPS sessions.

.. note::

   The AWS credentials configured here are used both to generate QuickSight embed URLs
   (in ``CUSTOM`` mode) and to SigV4-sign the calls to Aulasneo's Panorama API (in ``FREE``
   and ``SAAS`` modes).

Environment constraints
-----------------------

The backend deliberately refuses to run in situations where dashboards cannot work:

* **HTTPS required.** If ``HTTPS`` is not ``'on'``, the dashboard endpoint returns HTTP 421
  and the other dashboard calls raise an error. Serve the LMS over HTTPS.
* **No local/dev hosts in DEMO mode.** In ``DEMO`` mode the backend rejects the hosts
  ``localhost``, ``local.overhang.io``, and ``local.edly.io`` with an error explaining that
  Panorama will not work in testing or development environments. Use a real HTTPS domain.

URL mount point
---------------

The app's URLs are mounted under ``/panorama/api/`` on the LMS. The MFE calls, for example,
``https://<lms>/panorama/api/get-embed-url``. See :ref:`backend_api` for the full list.

Installing for development
--------------------------

To work on the backend against a local Open edX, add a small Tutor plugin that mounts your
checkout into the ``openedx`` image:

.. code-block:: python

   from tutor import hooks as tutor_hooks

   tutor_hooks.Filters.MOUNTED_DIRECTORIES.add_item(
       ("openedx", "panorama-openedx-backend")
   )

Then use ``tutor mounts`` to mount your local copy of the repository. For real deployments,
use the Panorama Tutor plugin instead, which adds the backend to the image's dependency list.

`Back to Home <index.html>`_