Add documentation on configuration and installation.

1 files changed, 117 insertions, 0 deletions

diff --git a/README.md b/README.md
index 76073d2..bd38f98 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,117 @@ used across the entire suite of the GeneNetwork services.
 
 ## Configuration
 
+The recommended way to pass configuration values to the application is via a
+configuration file passed in via the `GN_AUTH_CONF` environment variable. This
+variable simply holds the path to the configuration file, e.g.
+```sh
+export GN_AUTH_CONF="${HOME}/genenetwork/configs/gn_auth_conf.py"
+```
+
+The settings in the file above will override
+[the default settings](./gn_auth/settings.py).
+
+**NOTE**: For development purposes, you can override any of the settings in the
+default configuration or the `GN_AUTH_CONF` file by setting an environment
+variable of the same name as the variable you wish to override.
+/Please note that this is included to help with debugging - you should not use this live./
+
+### Configuration Variables
+
+| Variable | Used By/For | Description |
+| ---- | ---- | ---- |
+| `LOGLEVEL` | Logging system events | Useful for logging system events and debugging. The acceptable values are `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. The default value is `WARNING` which will log out all warnings, errors and critical conditions. |
+| `SECRET_KEY` | Flask | Used by flask to securely sign session cookies. See https://flask.palletsprojects.com/en/2.3.x/config/#SECRET_KEY. This setting is mandatory. If not provided, the system will not start. It is not provided by default, on purpose, to force the end-user to provide the value and prevent subtle bugs that can be experienced (especially with sessions) if this value is not set up. It would also be a **HUGE** security hole to provide a default value for this setting. |
+| `SQL_URI` | MariaDB connections | Used to connect to the MariaDB server |
+| `AUTH_DB` | SQLite connections | Used to connect to the Authentication/Authorisation database |
+| `AUTH_MIGRATIONS` | Migrations | Relative (to the repo root) path to the migration scripts for the auth(entic/oris)ation database |
+| `OAUTH2_SCOPE` | Supported OAuth2 scope for the application. |
+
 ## Installation
 
+The recommended way to install the application is using GNU Guix[^gnu-guix]. You
+could, hypothetically, safely install and run the application using Python's
+Distutils, but we have not tested that (hence you'd be on your own).
+
+The first step is to install GNU Guix[^gnu-guix] on your system. If you are
+already using some other Linux distribution, install Guix as a package manager
+on your system.
+
+Once you have Guix installed on your computer, you can now start **gn-auth** in
+one of three ways:
+
+* Using a development shell/environment (`guix shell ...`)
+* As a system container (mostly for deployments (`guix system container ...`))
+* Using a guix profile
+
+### Guix Shell
+
+This is the recommended way to start **gn-auth** if you intend to do any
+development on **gn-auth**. To do this, you need to be inside the **gn-auth**
+repository:
+
+```sh
+cd "${HOME}/genenetwork-projects/gn-auth"
+guix shell --container --network \
+  --share=<path-to-shareable-directory>=<path-of-share-in-shell> \
+  --development --file=guix.scm
+```
+
+The `--network` option allows the container to share the host network, and you
+can access the application with something like "http://localhost:<port>".
+
+The `--development` option installs all the dependencies in the shell that you
+need for development - including those which won't be in production but are
+needed for dev-work.
+
+The `--share` and `--expose` options are used to expose specific directories on
+the host system to your container. The `--expose` option exposes the specified
+directory in **read-only** mode. You cannot write to such a share. The `--share`
+option allows the shared directory to be writable from the shell.
+
+The `--share` and `--expose` options can be repeated expose as many directories
+to the shell as are needed.
+
+The `--container` option creates a container environment completely isolated
+from the rest of your system. This is the recommended way to do your
+development. Without the option, your host environment bleeds into your shell.
+
+Since providing the `--container` option isolates your shell, it means you will
+not have access to some command in the host within the shell environment. A lot
+of the times, this is a non-issue, and you can get by without them. If, however,
+you find yourself in one of the vanishingly-small instances where you require
+to leak your host environment into your development environment, then you know
+to simply omit the option.
+
+### Guix System Container
+
+Guix system containers are an entirely different beast from the development
+containers we mentioned in the section above.
+
+You can think of `guix shell --container ...` invocation as simply creating an
+isolated shell environment, but otherwise using the same kernel as the rest of
+your host system.
+
+A guix system container, `guix system container ...` on the other hand, creates
+a proper system container complete with it's own separate operating-system
+kernel.
+
+System containers are useful for deployment, not so much day-to-day development.
+
+### Guix Profile
+
+You can install **gn-auth** package into a profile with something like:
+```sh
+guix package --install-from-file=guix.scm --profile="${HOME}/opt/gn-auth"
+```
+
+You can then source that profile to run the application:
+
+```sh
+source ~/opt/gn-auth/etc/profile
+flask run --port=8081
+```
+
 ## Migrations
 
 **NOTE**: Do not create migration scripts manually. Use the processes indicated below.
@@ -144,3 +253,11 @@ pytest -k unit_test
 This application acts as an OAuth2 server, allowing the client applications to
 authenticate and access the API endpoints with the appropriate authorisation
 levels.
+
+
+------
+
+[^gnu-guix]: We consider the use of [GNU Guix](https://guix.gnu.org/) as a
+package manager in this documentation, but there is nothing preventing you from
+using it as your operating system of choice for the entire system should you so
+choose.