[v0.5.0] Review README (#113)

dojot · Oct 6, 2020 · 8245b68 · 8245b68
1 parent bc998bd
commit 8245b68
Show file tree

Hide file tree

Showing 12 changed files with 132 additions and 599 deletions.
diff --git a/README.md b/README.md
@@ -1,138 +1,160 @@
-# dojot Authentication service
+# **Auth**
 
-This service handles user authentication for the platform. Namely this is used to
-maintain the set of known users, and their associated roles. Should a user need
-to interact with the platform, this service is responsible for generating the JWT
-token to be used when doing so.
+This service handles user authentication for the platform. Namely this is used to maintain the set
+of known users, and their associated roles. Should a user need to interact with the platform, this
+service is responsible for generating the JWT token to be used when doing so.
 
-## Installation
+# Table of contents
 
-This service depends on a couple of python libraries to work. To install them, please run the
-commands below. These have been tested on an ubuntu 16.04 environment (same used when generating)
-the service's docker image.
+1. [Installation](#installation)
+   1. [Docker](#docker)
+   2. [Standalone](#standalone)
+2. [Configuration](#configuration)
+3. [Kafka Messages](#kafka-messages)
+   1. [Tenant creation](#tenant-creation)
+   1. [Tenant removal](#tenant-removal)
+4. [API](#api)
+5. [Tests](#tests)
+6. [Documentation](#documentation)
+7. [Issues and help](#issues-and-help)
 
-```shell
-# you may need sudo for those
-apt-get install -y python3-pip
-python3 setup.py
-```
+# **Installation**
+
+## **Docker**
 
-Another alternative is to use docker to run the service. To build the container, from the
-repository's  root:
+The recommended way to run the service is by using Docker. To build the container, run the following
+command from the repository's root:
 
 ```shell
-# you may need sudo on your machine: https://docs.docker.com/engine/installation/linux/linux-postinstall/
-docker build -t <tag> -f docker/Dockerfile .
+docker build -t <username>/<image>:<tag> -f docker/Dockerfile .
 ```
 
-## Configuration
+__NOTE THAT__ you have to add the username only if you want to send the image to some Docker
+Registry solution.
 
-### Database related configuration
+## **Standalone**
 
-Some auth configuration is made using environment variables.
-On a Linux system one can set a environment variable with the command
+This service depends on a couple of Python libraries to work. To install them, please run the
+commands below. These have been tested on an Ubuntu 16.04 environment (same used when generating)
+the service's docker image.
 
 ```shell
-  export VAR_NAME=varvalue
+# you may need sudo for those
+apt-get install -y python3-pip
+python3 setup.py
 ```
 
-on a docker-compose schema, one can set environment variables for a container
-Append the following configuration
+You will also need to create and populate the database tables before the first run. In the `python3`
+shell, run:
 
-```shell
-  environment:
-      VAR_NAME: "varvalue"
+```python
+from webRouter import db
+db.create_all()
 ```
 
-The default value is used if the configuration was not provided
-The following variables can be set
-
-* AUTH_DB_NAME
-  * database type. Current only postgres is supported
-  * default: postgres
-
-  * AUTH_DB_USER
-    * The username used to access the database
-    * default: auth
-
-  * AUTH_DB_PWD
-        * The password used to access the database
-        * default: empty password
-
-  * AUTH_DB_HOST
-        * The URL used to connect to the database
-        * default: http://postgres
-
-  * AUTH_KONG_URL
-        * The URL where the Kong service can be found
-        * If set to 'DISABLED' Auth won´t try to configure Kong and will generate secrets for the JWT tokens by itself.
-        * default: http://Kong:8001
-
-  * AUTH_TOKEN_EXP
-        * Expiration time in second for generated JWT tokens
-        * default: 420
+Now create the initial users, groups and permissions:
 
-  * AUTH_TOKEN_CHECK_SIGN
-        * Whether Auth should verify received JWT signatures. Enabling this will cause one extra query to be performed.
-        * default: False
-
-  * AUTH_CACHE_NAME
-        * Type of cache used. Currently only Redis is suported.
-        * If set to 'NOCACHE' auth will work without cache. Disabling cache usage considerably degrades performance.
-        * default: redis
-
-  * AUTH_CACHE_USER
-        * username to access the cache database
-        * default: redis
-
-  * AUTH_CACHE_PWD
-        * password to acces the cache database
-        * default: empty password
-
-  * AUTH_CACHE_HOST
-        * ip or hostname where the cache can be found
-        * default: redis
+```shell
+python3 initialConf.py
+```
 
-  * AUTH_CACHE_TTL
-        * Cache entry time to live in seconds
-        * default: 720
+# **Configuration**
+
+Before running the service, always check if the environment variables are suited to your
+environment.
+
+| Name | Description | Default value | Accepted values
+| ---- | ----------- | ------------- | ---------------
+| AUTH_CACHE_DATABASE | Cache database name (or number). | 0 | string
+| AUTH_CACHE_HOST | Address used to connect to the cache. | redis | hostname/IP
+| AUTH_CACHE_NAME | Type of cache used. Currently only Redis is supported. Setting to `NOCACHE` disables the cache - beware that disabling it considerably degrades performance | redis | string
+| AUTH_CACHE_PWD | Password to access the cache database. | empty password | string
+| AUTH_CACHE_TTL | Cache entry time to live in seconds. | 720 | number
+| AUTH_CACHE_USER | Username to access the cache database. | redis | string
+| AUTH_DB_CREATE | Whether to create the database when initializing or not. Does not remove nor overwrite if it already exists. | True | boolean
+| AUTH_DB_HOST | Address used to connect to the database. | http://postgres | hostname/IP
+| AUTH_DB_NAME | Type of database used. Currently only PostgreSQL is supported. | postgres | string
+| AUTH_DB_PWD | Database password. | empty password | string
+| AUTH_DB_USER | Database username. | auth | string
+| AUTH_EMAIL_HOST | SMTP server to be used. If set to `NOEMAIL`, this functionality is disabled. | NOEMAIL | string
+| AUTH_EMAIL_PASSWD | SMTP password. | empty string | string
+| AUTH_EMAIL_PORT | SMTP server port. | 587 | number
+| AUTH_EMAIL_TLS | Whether to enable TLS or not for SMTP server. | True | boolean
+| AUTH_EMAIL_USER | SMTP user. | empty string | string
+| AUTH_KONG_URL | Kong location (If set to `DISABLED` Auth won´t try to configure Kong and will generate secrets for the JWT tokens by itself). | http://kong:8001 | hostname/IP:port or DISABLE
+| AUTH_PASSWD_BLACKLIST | File of blacklisted passwords. | password_blacklist.txt | string
+| AUTH_PASSWD_HISTORY_LEN | Number of passwords to check to enforce the no password repetition policy. | 4 | number
+| AUTH_PASSWD_MIN_LEN | Minimum length for passwords. | 8 | number
+| AUTH_PASSWD_REQUEST_EXP | Password reset link expiration (in minutes). | 30 | number
+| AUTH_RESET_PWD_VIEW | When using a front end with Auth, define this link to point to the password reset view. | empty string | string
+| AUTH_SYSLOG | Which stream to output the log messages. If set to `SYSLOG`, a log file will be created in `/var/log`. | STDOUT | STDOUT, SYSLOG
+| AUTH_TOKEN_CHECK_SIGN | Whether Auth should verify received JWT signatures. Enabling this will cause one extra query to be performed. | False | boolean
+| AUTH_TOKEN_EXP | Expiration time in seconds for generated JWT tokens. | 420 | number
+| AUTH_USER_TMP_PWD | The default temporary password that is given to new users if `AUTH_EMAIL_HOST` is set to `NOEMAIL`. | temppwd | string
+| DATA_BROKER_URL | Data broker URL. | http://data-broker | IP/hostname
+| DOJOT_MANAGEMENT_TENANT | Dojot management tenant name. | dojot-management | string
+| DOJOT_MANAGEMENT_USER | Dojot management user name. | auth | string
+| KAFKA_HOST | Kafka host to publish messages to. | kafka:9092 | hostname/IP:port
+
+# **Kafka Messages**
+
+This service publishes some messages to Kafka that are related to tenancy lifecycle events. The
+default topic is `dojot-management.dojot.tenancy`. The topic can be changed via the
+`DOJOT_MANAGEMENT_TENANT`. If you set this variable to, for example, `mytesttenant`, the topic will
+be `mytesttenant.dojot.tenancy`.
+
+## **Tenant creation**
+
+This message is published whenever a new tenant is created. Its payload is a simple JSON:
+
+```json
+{
+  "type": "CREATE",
+  "tenant": "admin"
+}
+```
 
-  * AUTH_CACHE_DATABASE
-        * cach database name (or number)
-        * default: '0'
+## **Tenant removal**
 
-If you are running without docker, You will need to create and populate
-the database tables before the first run.
+This message is published whenever a tenant is removed. Its payload is a simple JSON:
 
-python3 shell:
 
-```shell
->>> from webRouter import db
->>> db.create_all()
+```json
+{
+  "type": "DELETE",
+  "tenant": "admin"
+}
 ```
 
-Create the initial users, groups and permissions
-
-```shell
-  python3 initialConf.py
-```
 
-## API
+# **API**
 
 The API documentation for this service is written as API blueprints.
 To generate a simple web page from it, one may run the commands below.
 
 ```shell
-npm install -g aglio # you may need sudo for this
-
-# static webpage
+# You might need sudo for this
+npm install -g aglio
+# Creates the static webpage
 aglio -i docs/auth.apib -o docs/auth.html
-
-# serve apis locally
+# Serves the APIs locally
 aglio -i docs/auth.apib -s
 ```
 
-## Tests
+# **Tests**
+
+Auth has some automated test scripts. We use [Dredd](http://dredd.org/en/latest/>) to execute them.
+Check the [Dockerfile](./tests/Dockerfile) used to build the test image to check how to run it.
+
+# **Documentation**
+
+Check the documentation for more information:
+
+- [Latest Auth API documentation](https://dojot.github.io/auth/apiary_latest.html#auth)
+- [Development Auth API documentation](https://dojot.github.io/auth/apiary_development.html#auth)
+- [Latest dojot platform documentation](https://dojotdocs.readthedocs.io/en/latest)
+
+# **Issues and help**
 
-Auth has some automated test scripts. We use `Dredd <http://dredd.org/en/latest/>`_ to execute them. Check the
-`Dockerfile <./tests/Dockerfile>`_ used to build the test image to check how to run it.
+If you found a problem or need help, leave an issue in the main
+[dojot repository](https://github.com/dojot/dojot) and we will help you!
diff --git a/auth/conf.py b/auth/conf.py
@@ -8,6 +8,12 @@
 LOGGER.addHandler(logging.StreamHandler())
 LOGGER.setLevel(logging.INFO)
 
+# Suggestion: instead of multiple variables, we could create and object to each configuration, like:
+# db: {
+#   name: ...,
+#   user: ...,
+# }
+
 # database related configuration
 dbName = os.environ.get("AUTH_DB_NAME", "dojot_auth")
 dbUser = os.environ.get("AUTH_DB_USER", "auth")
@@ -34,6 +40,8 @@
 # email related configuration
 emailHost = os.environ.get("AUTH_EMAIL_HOST", "NOEMAIL")
 emailPort = int(os.environ.get("AUTH_EMAIL_PORT", 587))
+# TODO: shouldn't this be treated as a boolean? If it must be a string, couldn't this be treated
+# differently, like downcasing the env var value and then checking if it equals to 'true'?
 emailTLS = (os.environ.get("AUTH_EMAIL_TLS", "true") in
             ['true', 'True', 'TRUE'])
 emailUsername = os.environ.get("AUTH_EMAIL_USER", "")
@@ -95,4 +103,5 @@
 # Kafka topic (subject) manager
 data_broker_host =  os.environ.get("DATA_BROKER_URL", 'http://data-broker')
 
+# TODO: we haven't tested this for a while, is this really working? And is this really necessary?
 rabbitmq_host = os.environ.get("RABBITMQ_HOST", "rabbitmq")
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_static/css/theme_overrides.css b/docs/_static/css/theme_overrides.css
diff --git a/docs/api.rst b/docs/api.rst