Add setup and management docs and LICENSE.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 The Alan Turing Institute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/content/management.rst

@@ -0,0 +1,72 @@
+Subscription Management
+-----------------------
+
+Using RCTab to manage subscriptions.
+
+Intro
++++++
+
+After completing the setup steps, you will have an RCTab system deployed to Azure.
+This means that:
+
+* The Usage and Status functions run on an schedule to collect information about subscriptions and post it to the web server.
+* The Controller function will check hourly to see whether any subscriptions need to be turned off or on.
+  Note that, by default, only subscriptions in the whitelist will be turned on or off.
+  See `Rollout`_ for more details.
+* The web server will email users about changes to their subscriptions.
+* Admins can install the CLI to check or adjust subscriptions' budgets, expiration dates, etc.
+* Admins and other users can log in to the front-end, which should have the URL of ``rctab-{ticker}-{orgname}@azurewebsites.net``.
+  This is often the quickest way to check a subscription's balance and history of approvals.
+* Admins can connect directly to the database (e.g. with `psql`) if they need more detail than the CLI or frontend provides.
+  The database admin password can be found in a keyvault on Azure.
+
+Rollout
++++++++
+
+To enable a gradual rollout of the system, RCTab has a whitelist.
+By default, RCTab will only enable/disable and send emails for subscriptions in the whitelist, which starts out empty.
+Once you are happy that RCTab has deployed successfully, that it is collecting data, that you can log into the frontend and set `Approvals and Allocations`_ using the CLI, you can use Pulumi to either add subscriptions to the ``WHITELIST`` environment variable or roll out to all subscriptions by setting the ``IGNORE_WHITELIST`` environment variable.
+
+Ignoring Subscriptions
+======================
+
+The whitelist is one way to get RCTab to ignore subscriptions.
+Subscriptions that aren't on the whitelist will not be enabled/disabled and will not receive emails but their data will be collected.
+There are two other ways to determine whether RCTab will ignore a subscription:
+
+* A subscription can be marked as "persistent" with the CLI.
+  "Persistent" subscriptions do receive emails but will not be disbaled.
+* A subscription can be placed outside of the management group that RCTab has permissions over.
+  In this case, RCTab will have no knowledge of the subscription, will not collect data, will not send emails and will not disable it.
+
+Approvals and Allocations
++++++++++++++++++++++++++
+
+RCTab will try to disable all subscriptions that it can see (i.e. that it is collecting data for with the Status and Usage functions) unless they have approvals.
+To create an approval for a subscription, use the CLI.
+To review approvals for a subscription, go to that subscription's detail page on the frontend.
+An approval is like a grant in that it covers some amount of spending over some time period.
+To make use of an approval, a subscription additionally needs an allocation (also created with the CLI).
+An allocation determines how much of the approved amount is available to spend right now.
+To extend an approval, you can make a £0 approval with a later end date.
+To reduce the amount of an approval, you can make a negative allocation followed by a negative approval.
+
+Subscription Lifecycle
+++++++++++++++++++++++
+
+The typical lifecycle of subscription managed by RCTab might be as follows:
+
+#. An admin creates a subscription on Azure (e.g. via the portal or CLI).
+   Note that RCTab does not create subscriptions, it only enables/disables them.
+   The subscription is placed into the management group where the function apps have the requisite permissions.
+#. The admin manually adds the subscription to RCTab with the CLI.
+   If it isn't added manually, it will be picked up by the Status or Usage app.
+#. An approval and an allocation are made for the subscription with the CLI.
+#. When the subscription approaches its budget or expiration date, RCTab will send an email to users with role assignments.
+#. Users of the subscription can request a budget increase or an extension from the admins.
+#. If this is granted, the admin can extend the approval and/or make a new allocation with the CLI.
+#. If the request is denied, the subscription will eventually be disabled by RCTab.
+   Users will be notified by email.
+   Azure will permanently delete the subscription after approximately 90 days.
+#. The subscription can be re-activated before the 90 days are up.
+#. If the subscription is not re-activated, RCTab will mark the the subscription as "abolished" and archive it.

docs/content/setup.rst

@@ -0,0 +1,30 @@
+Setup
+-----
+
+Azure
++++++
+
+RCTab can be deployed to Azure automatically with our Infrastructure repository.
+There are some prerequisites, which are covered in the Infrastructure docs.
+Once the deployment has finished, the API and Function Apps will pull their respective images from Docker Hub and immediately start collecting data.
+
+Local
++++++
+
+The simplest setup would comprise the web server, database and one or more function apps running on your local (Linux or MacOS) machine.
+The steps to set this up are:
+
+#. Clone the API repo and follow the development instructions in the API docs to set up a database & web server and to register an application with Active Directory.
+#. Clone the CLI repo and install the CLI package into a virtual environment, as per the CLI docs.
+#. Clone the Function Apps repo and follow the developer installation instructions in the Function Apps docs.
+   Note that the function apps rely on several environment variables to be able to communicate with the web server.
+   In particular, they need to be given the hostname and port of the web server and each function app needs the private half of a key pair (the public halves are set as environment variables on the web server).
+#. As per their documentation, each of the function apps requires a different set of permissions to function correctly.
+   When you run the function apps locally, they will try to obtain your credentials from several places, such as Visual Studio Code and the Azure CLI.
+   Therefore, you will need to make sure that you have the correct Azure RBAC permissions and that you are logged in to Azure via Visual Studio or the Azure CLI before running the functions locally.
+#. Once you are logged in and have the web server started, you can run the Status and Usage functions to collect data.
+#. With data in your database, you can do any of the following:
+
+   * View it via the web server frontend (typically on ``0.0.0.0:8000``).
+   * Approve some budget for your subscription to spend with the RCTab CLI.
+   * Disable and enable subscriptions by running the Controller function app.

docs/index.rst

@@ -22,14 +22,15 @@ Components
 
 The complete system comprises:
 
-* A web server `web server <https://github.com/alan-turing-institute/rctab-api>`_.
-* The `CLI <https://github.com/alan-turing-institute/rctab-cli>`_, which allows command line interaction with the web server.
-* Three `Function Apps <https://github.com/alan-turing-institute/rctab-functions>`_, which run background jobs to interact with Azure:
+* A web server (A.K.A. the "RCTab API").
+* The CLI, which allows command line interaction with the web server.
+* Three function apps, which run background jobs to interact with Azure:
 
   * Usage: Gets usage data from Azure and posts to this API.
   * Status: Gets information about subscriptions from Azure, such as state and RBAC and posts to this API.
   * Controller: Gets list of subscriptions and their desired state from the API and then enables or disables subscriptions on Azure.
 * An `authentication library <https://github.com/alan-turing-institute/fastapimsal>`_, which handles authentication using Microsoft's MSAL library for FastAPI.
+* Logging and alerts.
 
 Contribute
 ++++++++++
@@ -57,8 +58,8 @@ If you need to get in touch with us, please open an issue on our `GitHub repo <h
 
    API docs <https://rctab-api.readthedocs.io/en/latest/>
    API repository <https://github.com/alan-turing-institute/rctab-api>
-   Functions docs <https://rctab-functions.readthedocs.io/en/latest/>
-   Functions repository <https://github.com/alan-turing-institute/rctab-functions>
+   Function Apps docs <https://rctab-functions.readthedocs.io/en/latest/>
+   Function Apps repository <https://github.com/alan-turing-institute/rctab-functions>
    CLI docs <https://rctab-cli.readthedocs.io/en/latest/>
    CLI repository <https://github.com/alan-turing-institute/rctab-cli>
    Infrastructure docs <https://rctab-infrastructure.readthedocs.io/en/latest/>