Developer Docs for Auth MS

cli/DEVELOPER.md

@@ -46,6 +46,76 @@ The CLI has two layers of code:
   is responsible for. It also
   has helper functions that can be used across the CLI.
 
+### TOML File
+
+The base configuration file used by the CLI is
+the _dtaas.toml_ file.
+
+This is divided into 3 sections:
+
+- The Global variables:
+
+```toml
+name = "Digital Twin as a Service (DTaaS)"
+version = "0.1.0"
+owner = "The INTO-CPS-Association"
+git-repo = "https://github.com/into-cps-association/DTaaS.git"
+```
+
+These define the name, version, owner and git-repo of the DTaaS instance.
+Currently, these aren't directly used in the CLI and serve the purpose
+of documentation and reference.
+
+- Common Instance Variables
+
+```toml
+[common]
+# absolute path to the DTaaS application directory
+server-dns = "localhost"
+path = "/home/Desktop/DTaaS"
+```
+
+The _path_ variable is used globally by the CLI.
+It is required while creating new workspace files,
+to run bash commands and create new docker services.
+
+The _server-dns_ variable is used to decide if
+the DTaaS instance is a localhost instance or a server
+deploy instance. In the case of server deploy,
+it is used to define the routes of the server type
+docker compose services appropriately.
+
+- Users variables
+
+```toml
+[users]
+# matching user info must present in this config file
+add = ["username1","username2", "username3"]
+delete = ["username2", "username3"]
+
+[users.username1]
+email = "[email protected]"
+```
+
+This section firstly has two important lists, add and delete.
+The new users to be created, or current users to be removed
+from the instance using the CLI are fetched from here in the code.
+
+Additionally, each unique _user_ identified by their _username_
+has an _email_ variable, which should have the email of the user
+as registered on the Gitlab instance. This is currently NOT IN USE.
+It is aimed to be incorporated in future versions.
+
+- Website Client variables
+
+```toml
+[client.web]
+config = "/home/Desktop/DTaaS/env.local.js"
+```
+
+These variables are currently not in use, and will be incorporated
+in future work.
+
 ## Setup
 
 ```bash
@@ -112,4 +182,23 @@ and publish your package to PyPI using poetry:
 
 ```bash
 poetry publish
-```
+```
+
+## Future work
+
+The final aim for the CLI is to be the standard way that
+admins setup, manage, and interact with the DTaaS instance.
+Although the base structure for the CLI is set up and
+the commands to manage users have been incorporated, we are
+a long way from our final aim.
+
+The following are the next steps for the CLI:
+
+- Incorporating the AuthMS _conf_ file rules
+  in the user management commands.
+
+- [Bug fix] Currently users with usernames containing
+  a '.' in it aren't handled well by the CLI and result in errors.
+  This is because '.' is a special character for labels in docker compose.
+  We need to include such usernames, simply by internally replacing
+  '.' instances in usernames by '-' or '_'.

docker/README.md

@@ -112,6 +112,32 @@ the publication of images to Docker Hub.
 :stop_sign: This publishing step is managed
 only by project maintainers. Regular developers can skip this step.
 
+The DTaaS development team publishes reusable packages which are then
+put together to form the complete DTaaS application.
+
+The packages are published on
+[github](https://github.com/orgs/INTO-CPS-Association/packages?repo_name=DTaaS),
+[npmjs](https://www.npmjs.com/org/into-cps-association), and
+[docker hub](https://hub.docker.com/u/intocps) repositories.
+
+The packages on
+[github](https://github.com/orgs/INTO-CPS-Association/packages?repo_name=DTaaS)
+are published more frequently but are not user tested.
+The packages on [npmjs](https://www.npmjs.com/org/into-cps-association)
+and [docker hub](https://hub.docker.com/u/intocps)
+are published at least once per release.
+The regular users are encouraged to use the packages from npm and docker.
+
+A brief explanation of the packages is given below.
+
+| Package Name | Description | Documentation for | Availability |
+|:----|:----|:----|:----|
+| dtaas-web | React web application | [container image](client/docker.md) | [docker hub](https://hub.docker.com/r/intocps/dtaas-web) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/container/dtaas-web) |
+| libms |Library microservice | [npm package](servers/lib/npm.md) | [npmjs](https://www.npmjs.com/package/@into-cps-association/libms) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/npm/libms) |
+| | | [container image](servers/lib/docker.md) | [docker hub](https://hub.docker.com/r/intocps/libms) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/container/libms) |
+| runner | REST API wrapper for multiple scripts/programs | [npm package](../user/servers/execution/runner/README.md) | [npmjs](https://www.npmjs.com/package/@into-cps-association/runner) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/npm/runner) |
+| ml-workspace-minimal (fork of [ml-workspace](https://github.com/ml-tooling/ml-workspace)) | User workspace | not available | [docker hub](https://hub.docker.com/r/intocps/ml-workspace-minimal/tags). Please note that this package is **highly experimental** and only v0.15.0-b2 is usable now. |
+
 ### React Website
 
 ```sh

docs/admin/cli.md

@@ -74,7 +74,7 @@ Then simply:
 dtaas admin user add
 ```
 
-#### Caveat
+#### Caveats
 
 This brings up the containers, without the AuthMS authentication.
 
@@ -99,7 +99,7 @@ rule.onlyu3.rule=PathPrefix(`/user3`)
 rule.onlyu3.whitelist = [email protected]
 ```
 
-Run the appropritate command for a server installation:
+- Run the appropritate command for a server installation:
 
 ```bash
 docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth
@@ -135,3 +135,7 @@ dtaas admin user delete
 - _user add_ and _user delete_ CLIs return an
   error if the _add_ and _delete_ lists in
   _dtaas.toml_ are empty, respectively.
+
+- '.' are a special character. Currently, usernames which have
+  '.'s in them cannot be added properly through the CLI.
+  This is an active issue that will be resolved in future releases.

docs/admin/servers/auth.md

@@ -143,6 +143,15 @@ account should be included in the whitelist.
 This restricts access of the resource,
 allowing only users mentioned in the whitelist.
 
+## User management
+
+DTaaS provides an easy way to add
+and remove additional users from your
+DTaaS instance.
+
+All such user management can be
+done via the [DTaaS CLI](../cli.md)
+
 ## Limitation
 
 The rules in _conf.*_ file are not dynamically loaded into
@@ -153,3 +162,15 @@ All the existing user sessions get invalidated when
 the **traefik-forward-auth** restarts.
 
 Use a simple command on the terminal.
+
+- For a local instance:
+
+```bash
+docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth
+```
+
+- For a server instance:
+
+```bash
+docker compose -f compose.server.yml --env-file .env.server up -d --force-recreate traefik-forward-auth
+```