docs: introduce deployment & development guides

Add one page covering deployment issues and one page covering
development.

The motivation of introducing these docs right now is to ensure
there's a place where the authentication scheme can be documented.
Other sections of the docs are light on detail at the moment.

docs/api-guide.rst

@@ -18,8 +18,13 @@ For a full reference on the available endpoints, see:
 Authentication
 --------------
 
-Authentication is currently unimplemented in exodus-gw; any clients with
-access to the service can perform all operations.
+The exodus-gw API does not include any direct support for authentication and is
+instead expected to be deployed behind a reverse-proxy implementing any desired
+authentication mechanism. Consult your organization's internal documentation for
+authentication info for your specific exodus-gw installation.
+
+See :ref:`deploy-guide` for more information on how to integrate an authentication
+mechanism.
 
 
 Uploading blobs

docs/deployment.rst

@@ -0,0 +1,75 @@
+.. _deploy-guide:
+
+Deployment Guide
+================
+
+
+Target platform
+---------------
+
+exodus-gw is an ASGI application which may be deployed using any ASGI-compliant
+web server. The development team's recommended setup is summarized as:
+
+- Use OpenShift >= 4.x to deploy the service.
+
+- Use the exodus-gw images at https://quay.io/repository/exodus/exodus-gw to run
+  the service. These images run the service using gunicorn & uvicorn on RHEL8.
+
+  In general, the
+  `uvicorn deployment advice <https://www.uvicorn.org/deployment/>`_
+  applies.
+
+- Deploy the service's primary container behind a reverse-proxy implementing
+  authentication according to your organization's needs (see next section).
+
+
+Authentication & Authorization
+------------------------------
+
+The exodus-gw service does not implement any authentication mechanism. It is instead
+designed to integrate with a reverse-proxy implementing any desired mechanism.
+
+.. warning::
+    If exodus-gw is deployed without an authenticating reverse-proxy, the service must
+    be considered completely unsecured - all users will be able to perform all operations.
+
+This reverse-proxy must add an ``X-RhApiPlatform-CallContext`` header onto all incoming
+requests. This header must contain a base64-encoded form of the following JSON object:
+
+.. code-block:: json
+
+  {
+    "client": {
+      "roles": ["someRole", "anotherRole"],
+      "authenticated": true,
+      "serviceAccountId": "clientappname"
+    },
+    "user": {
+      "roles": ["viewer"],
+      "authenticated": true,
+      "internalUsername": "someuser"
+    }
+  }
+
+The ``roles`` and ``authenticated`` fields influence whether an exodus-gw request will be
+permitted - the necessary roles are documented on relevant exodus-gw API endpoints.
+Other fields are unused or used only for logging.
+
+The separate ``client`` and ``user`` fields can be used to separate service accounts
+(machine users) from human users, but this does not affect exodus-gw.
+
+Within Red Hat, a container known as "platform-sidecar" is used as the reverse proxy - consult
+internal documentation for information on this component. In other contexts, any reverse
+proxy may be used as long as it produces headers according to the scheme documented above.
+
+
+Settings
+--------
+
+.. autoclass:: exodus_gw.settings.Settings()
+    :members:
+
+    exodus-gw may be configured by the following settings.
+
+    Each settings value may be overridden using an environment variable of the
+    same name, prefixed with ``EXODUS_GW_`` (example: ``EXODUS_GW_CALL_CONTEXT_HEADER``).

docs/development.rst

@@ -0,0 +1,34 @@
+.. _dev-guide:
+
+Development Guide
+=================
+
+This document contains useful info for developers contributing
+to the exodus-gw project.
+
+
+Spoofing authentication
+-----------------------
+
+The exodus-gw service parses an ``X-RhApiPlatform-CallContext`` header for information
+relating to authentication & authorization; see :ref:`deploy-guide` for more info on
+this scheme.
+
+During development, arbitrary values for this header may be used to test the
+behavior of endpoints with various roles. However, due to the format of this header,
+generating these values by hand can be cumbersome.
+
+To assist in this, a helper script is provided in the exodus-gw repo at
+``scripts/call-context``. This script accepts any number of role names as arguments
+and produces a header value which will produce an authenticated & authorized request
+using those roles.
+
+For example, if we want to use ``curl`` to make a request to an endpoint needing
+``qa-uploader`` role, we can use the following command:
+
+.. code-block:: shell
+
+    curl \
+      -H "X-RhApiPlatform-CallContext: $(scripts/call-context qa-uploader)" \
+      http://localhost:8080/some/qa/endpoint
+

docs/index.rst

@@ -9,6 +9,8 @@ Publishing microservice for Red Hat's Content Delivery Network.
 
    api-guide
    api
+   deployment
+   development
 
 Overview
 --------

exodus_gw/settings.py

@@ -4,11 +4,10 @@
 
 
 class Settings(BaseSettings):
-    """Settings for the server.
-
-    Each setting defined here can be overridden by an environment variable
-    of the same name, prefixed with "EXODUS_GW_".
-    """
+    # Settings for the server.
+    #
+    # Each setting defined here can be overridden by an environment variable
+    # of the same name, prefixed with "EXODUS_GW_".
 
     call_context_header: str = "X-RhApiPlatform-CallContext"
     """Name of the header from which to extract call context (for authentication