Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Developer Docs for Auth MS #811

Closed
wants to merge 8 commits into from
Closed

Developer Docs for Auth MS #811

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ce40369
Developer Docs for Auth MS
astitva1905 Jun 9, 2024
99e4439
Adds AuthMS Drawio and resolves documentation issues
astitva1905 Jun 12, 2024
2e3cdc0
uses better quality uml diagrams
astitva1905 Jun 16, 2024
31c8d56
resolves code climate issues
astitva1905 Jun 16, 2024
05319f3
resolves code climate issues
astitva1905 Jun 16, 2024
2e765d4
final codeclimate issues resolved
astitva1905 Jun 16, 2024
f0d133b
PR review
astitva1905 Jun 16, 2024
543d612
changes instance to gitlab.foo
astitva1905 Jun 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 90 additions & 1 deletion cli/DEVELOPER.md
View file
Open in desktop
astitva1905 marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -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"
astitva1905 marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down Expand Up @@ -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 '_'.
27 changes: 27 additions & 0 deletions docker/README.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please check the urls

Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,33 @@ 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
Expand Down
33 changes: 17 additions & 16 deletions docs/admin/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Then simply:
dtaas admin user add
```

#### Caveat
#### Caveats

This brings up the containers, without the AuthMS authentication.

Expand All @@ -87,23 +87,20 @@ This brings up the containers, without the AuthMS authentication.

- Go to the _docker_ directory

```bash
cd <DTaaS>/deploy/docker
```

```bash
cd <DTaaS>/deploy/docker
```
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fenced code blocks should be surrounded by blank lines

- Add three lines to the `conf.server` file
```txt
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fenced code blocks should be surrounded by blank lines

rule.onlyu3.action=auth
rule.onlyu3.rule=PathPrefix(`/user3`)
rule.onlyu3.whitelist = [email protected]
```

```txt
rule.onlyu3.action=auth
rule.onlyu3.rule=PathPrefix(`/user3`)
rule.onlyu3.whitelist = [email protected]
```

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
```
- Run the appropritate command for a server installation:
```bash
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fenced code blocks should be surrounded by blank lines

docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth
```

The new users are now added to the DTaaS
instance, with authorization enabled.
Expand Down Expand Up @@ -135,3 +132,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.
21 changes: 21 additions & 0 deletions docs/admin/servers/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
Loading