Docs: Add documentation

1 files changed, 119 insertions, 0 deletions

diff --git a/README.md b/README.md
index f4ccdfd..76073d2 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,125 @@
 # GeneNetwork Auth
 
+[![GeneNetwork Auth CI
+badge](https://ci.genenetwork.org/badge/gn-auth.svg)](https://ci.genenetwork.org/jobs/gn-auth)
+[![GeneNetwork Auth pylint CI
+badge](https://ci.genenetwork.org/badge/gn-auth-pylint.svg)](https://ci.genenetwork.org/jobs/gn-auth-pylint)
+[![GeneNetwork Auth mypy CI badge](https://ci.genenetwork.org/badge/gn-auth-mypy.svg)](https://ci.genenetwork.org/jobs/gn-auth-mypy)
+
 This project is for the GeneNetwork Authentication/Authorisation server to be
 used across the entire suite of the GeneNetwork services.
 
+## Configuration
+
+## Installation
+
+## Migrations
+
+**NOTE**: Do not create migration scripts manually. Use the processes indicated below.
+
+### Authentication/Authorisation Migrations
+
+The migration scripts for the authentication and authorisation system are in the *migrations/auth* folder in the root of the repository.
+
+To create an new migration script for the, do:
+
+```bash
+$ yoyo new -m "<description of the migration>" ./migrations/auth/
+```
+
+The command will ask whether you want to save the migration configuration, e.g.
+
+```bash
+$ yoyo new --config=yoyo.auth.ini -m "testing a new migration"
+Error: could not open editor!
+Created file ./migrations/auth/20221103_02_HBzwk-testing-a-new-migration.py
+Save migration configuration to yoyo.ini?
+This is saved in plain text and contains your database password.
+
+Answering 'y' means you do not have to specify the migration source or database connection for future runs [yn]:
+```
+
+If you specify `y` then a file named yoyo.ini will be created in your current working directory, and you can refer to it to avoid providing the `./migrations/auth` explicitly.
+
+Now you can open and edit the scripts to provide the appropriate SQL statements to update or rollback your schema.
+
+### Running the Migrations
+
+To apply the migrations, you can do something like:
+
+```bash
+$ yoyo apply --database="sqlite:////tmp/test-auth.db" ./migrations/auth/
+
+[20221103_01_js9ub-initialise-the-auth-entic-oris-ation-database]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221103_02_sGrIs-create-user-credentials-table]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221108_01_CoxYh-create-the-groups-table]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221108_02_wxTr9-create-privileges-table]
+Shall I apply this migration? [Ynvdaqjk?]: Y
 
+...
+```
+
+If you have previously initialised the yoyo config file, you can put the database uri in the configuration file and just provide it to avoid the prompt to save the configuration.
+
+As a convenience, and to enable the CI/CD to apply the migrations automatically, I have provided a flask cli command that can be run with:
+
+```bash
+$ export FLASK_APP=main.py
+$ flask apply-migrations
+```
+
+This expects that the following two configuration variables are set in the application:
+
+* `AUTH_MIGRATIONS`: path to the migration scripts
+* `AUTH_DB`: path to the sqlite database file (will be created if absent)
+
+To enable you to run the OAuth2 server without HTTPS, you need to setup the
+following environment variable(s):
+
+* `export AUTHLIB_INSECURE_TRANSPORT=true`: Allows you to run the Authlib server
+  without HTTPS on your development machine.
+
+## Running
+
+### Development
+
+To run the application during development:
+
+```sh
+export FLASK_DEBUG=1
+export FLASK_APP="main.py"
+export AUTHLIB_INSECURE_TRANSPORT=true
+export GN_AUTH_CONF="${HOME}/genenetwork/configs/gn_auth_conf.py"
+flask run --port=8081
+```
+
+replace the `GN_AUTH_CONF` file with the correct path for your environment.
+
+### Production
+
+You can run the application on production with GUnicorn with something like:
+
+```sh
+gunicorn --bind 0.0.0.0:8081 --workers 6 --keep-alive 6000 --max-requests 10 \
+	--max-requests-jitter 5 --timeout 1200 wsgi:app
+```
 
 ## Checks
 
+Running checks ensures the code is good, and the application actually does what
+it is expected to do.
+
+The checks we do are
+- Lint-checks
+- Type-checks
+- Unit tests
+
 ### Linting
 
 ```bash
@@ -25,3 +138,9 @@ mypy --show-error-codes .
 export AUTHLIB_INSECURE_TRANSPORT=true
 pytest -k unit_test
 ```
+
+## OAuth2
+
+This application acts as an OAuth2 server, allowing the client applications to
+authenticate and access the API endpoints with the appropriate authorisation
+levels.