docker documentation

docs/admin/docker/README.md

@@ -0,0 +1,51 @@
+# Install DTaaS using Docker
+
+This guide explains how to install the docker-based version
+of DTaaS software.
+
+## Prerequisites
+
+**[Docker](https://www.docker.com/)** - It is important to have docker installed on your system/ server. We highly recommend using [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+
+**[Gitlab Instance](https://about.gitlab.com/install/)** - DTaaS Authorization uses Gitlab OAuth2.0 authentication. Thus, to enable user authentication and authorization for your DTaaS instance, you will need a Gitlab Instance. You can bring up a private instance (recommended), or you can use [gitlab.com](www.gitlab.com) itself.
+
+## Steps
+
+### Clone the DTaaS repository:
+
+```bash
+git clone https://github.com/INTO-CPS-Association/DTaaS.git
+```
+
+### Setup Gitlab Applications
+
+Refer to [Gitlab Application Setup Documentation](https://github.com/into-cps-association/dtaas/docs/admin/docker/gitlab.md).
+
+### Set the Client env file
+
+Refer to the [Client Setup Documentation](https://github.com/into-cps-association/dtaas/docs/admin/docker/client.md).
+
+### Set the environment variables
+
+- Switch to the docker directory:
+
+```
+cd <DTaaS-Path>/docker
+```
+
+- Setup the _.env_ file : This file contains
+  variables that need to be set to your specific
+  use case.
+
+    | URL Path | Example |Access Granted to |
+  |:------------|:---------------|:---------------|
+  | DTAAS_DIR | '/home/Desktop/DTaaS' | Full path to the DTaaS directory. This is an absolute path with no trailing slash. |
+  | SERVER_DNS | <http>_foo.com_</http> or <http>_localhost_</http> | The server DNS, if you are deploying with a dedicated server. Remember not use  <http:>http(s)</http:> at the beginning of the DNS string |
+  | OAUTH_URL | <http>_gitlab.foo.com_<http/> | The URL of your Gitlab instance |
+  | CLIENT_ID | 'xx' | The ID of your OAuth application |
+  | CLIENT_SECRET | 'xx' | The Secret of your OAuth application |
+  | OAUTH_SECRET | 'random-secret-string' | Any private random string |
+  | username1 | 'user1' | The gitlab instance username of a user of DTaaS |
+  | username2 | 'user2' | The gitlab instance username of a user of DTaaS |
+  | CLIENT_CONFIG | '/Users/<Username>/DTaaS/deploy/config/client/env.js' | Full path to env.js file for client |
+

docs/admin/docker/client.md

@@ -0,0 +1,77 @@
+# Client Environment Setup
+
+The DTaaS Client website requires certain environment variables to be hosted.
+These are set in a _.js_ file. You can find and use such files given in
+_<DTaaS>/deploy/config/client_ directory.
+
+See the definitions and examples below:
+
+```js
+if (typeof window !== 'undefined') {
+window.env = {
+    REACT_APP_ENVIRONMENT: "prod | dev",
+    REACT_APP_URL: "URL for the gateway",
+    REACT_APP_URL_BASENAME: "Base URL for the client website"(optional),
+    REACT_APP_URL_DTLINK: "Endpoint for the Digital Twin",
+    REACT_APP_URL_LIBLINK: "Endpoint for the Library Assets",
+    REACT_APP_WORKBENCHLINK_VNCDESKTOP: "Endpoint for the VNC Desktop link",
+    REACT_APP_WORKBENCHLINK_VSCODE: "Endpoint for the VS Code link",
+    REACT_APP_WORKBENCHLINK_JUPYTERLAB: "Endpoint for the Jupyter Lab link",
+    REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK:
+    "Endpoint for the Jupyter Notebook link",
+    REACT_APP_CLIENT_ID: 'AppID genereated by the gitlab OAuth provider',
+    REACT_APP_AUTH_AUTHORITY: 'URL of the private gitlab instance',
+    REACT_APP_REDIRECT_URI: 'URL of the homepage for the logged in users of the website',
+    REACT_APP_LOGOUT_REDIRECT_URI: 'URL of the homepage for the anonymous users of the website',
+    REACT_APP_GITLAB_SCOPES: 'OAuth scopes. These should match with the scopes set in gitlab OAuth provider',
+};
+};
+
+// Example values with no base URL. Trailing and ending slashes are optional.
+if (typeof window !== 'undefined') {
+window.env = {
+    REACT_APP_ENVIRONMENT: 'prod',
+    REACT_APP_URL: 'https://foo.com/',
+    REACT_APP_URL_BASENAME: '',
+    REACT_APP_URL_DTLINK: '/lab',
+    REACT_APP_URL_LIBLINK: '',
+    REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword',
+    REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/',
+    REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab',
+    REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '',
+    REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0',
+    REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/',
+    REACT_APP_REDIRECT_URI: 'https://foo.com/Library',
+    REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/',
+    REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
+};
+};
+
+
+// Example values with "bar" as basename URL.
+//Trailing and ending slashes are optional.
+if (typeof window !== 'undefined') {
+window.env = {
+    REACT_APP_ENVIRONMENT: "dev",
+    REACT_APP_URL: 'https://foo.com/',
+    REACT_APP_URL_BASENAME: 'bar',
+    REACT_APP_URL_DTLINK: '/lab',
+    REACT_APP_URL_LIBLINK: '',
+    REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword',
+    REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/',
+    REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab',
+    REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '',
+    REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0',
+    REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/',
+    REACT_APP_REDIRECT_URI: 'https://foo.com/bar/Library',
+    REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/bar',
+    REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
+};
+};
+```
+Setup the variables in an appropriate _.js_ file, and note down the path of
+this file. This path needs to be set in the _<DTaaS>/docker/.env_ file.
+For a _localhost_ setup, you can directly use the sample
+_<DTaaS>/deploy/config/client/env.local.js_ to test your setup. However,
+we recommend eventually creating a Gitlab client application, and
+setting the *REACT_APP_CLIENT_ID* to the ID of this application. 

docs/admin/docker/gitlab.md

@@ -0,0 +1,40 @@
+# Gitlab Applications Setup
+
+## Gitlab Client Auth App
+
+- Login to your Gitlab instance as an admin.
+  Head over to the Admin area.
+
+- Go to the Applications tab. Click on "Add
+  a new application" on the top right.
+
+  ![Add a new application](gitlab-app-1.png)
+
+- Write a suitable name for the application,
+  and add _{server-dns}/Library_ to the Redirect URI section. Keep the Trusted & Confidential
+  checkboxes unticked.
+
+  ![](image.png)
+
+- Select the 5 required scopes: api, read_user,
+  read_repository, openid, profile. Click on
+  Save Application.
+
+- Copy the Application ID displayed, and click
+  on continue. Your application is now created.
+
+## Gitlab Server Auth App
+
+This step isn't required for a _localhost_ deploy which doesn't need user authentication.
+Follow the steps if you require user authentication. 
+
+- Follow similar steps as the previous section
+  to create a new Gitlab application.
+
+- Give this application a unique name, and add
+  *{server_dns}/_oauth* to the Redirect URI section. Keep the Trusted & Confidential
+  checkboxes unticked.
+
+- Select the read_user scope. Click on Save
+  Application. Note down both the Application ID,
+  and Secret shown. Your application is now created.

docs/admin/servers/auth.md

@@ -35,7 +35,7 @@ Here are the steps to get started:
   It's recommended to use a self-hosted GitLab instance, which you will use in
   other parts of the DTaaS application.
 
-**3. Define Callback and Logout URLs:**
+**3. Callback and Logout URLs:**
 
 - For the web / server authorization flow to function correctly, you need two URLs:
   a callback URL and a logout URL.
@@ -139,8 +139,8 @@ allowing only users mentioned in the whitelist.
 The rules in _conf_ file are not dynamically loaded into
 the **traefik-forward-auth** microservice.
 Any change in the _conf_ file requires
-retart of **traefik-forward-auth** for the changes to take effect.
+restart of **traefik-forward-auth** for the changes to take effect.
 All the existing user sessions get invalidated when
 the **traefik-forward-auth** restarts.
 
-Use a simple command on the terminal.
+Use a simple command on the terminal.