Add portainer-based GUI guide for localhost (#1037 and #1039)

---------
Co-authored-by: aryanpingle <[email protected]>

docs/admin/guides/localhost_portainer.md

@@ -0,0 +1,158 @@
+# Install DTaaS on localhost (GUI)
+
+The installation instructions provided in this README are
+ideal for running the DTaaS on localhost via a Graphical User
+Interface (GUI).
+This installation is ideal for single users intending to use
+DTaaS on their own computers.
+
+## Design
+
+An illustration of the docker containers used and the authorization
+setup is shown here.
+
+![Traefik OAuth](../localhost.png)
+
+## Requirements
+
+The installation requirements to run this docker version of the DTaaS are:
+
+- docker desktop / docker CLI with compose plugin
+- User account on _gitlab.com_
+
+<!-- markdownlint-disable MD046 -->
+<!-- prettier-ignore -->
+!!! tip
+    The frontend website requires authorization.
+    The default authorization configuration works for _gitlab.com_.
+    If you desire to use locally hosted gitlab instance, please see
+    the [client docs](../client/auth.md).
+<!-- markdownlint-enable MD046 -->
+
+## Download a Release
+
+You can find all releases of the DTaaS software on the
+[GitHub releases page](https://github.com/INTO-CPS-Association/DTaaS/releases).
+Download the latest release as a zip file, and extract it to any directory
+on your system.
+
+In this guide we will assume the contents of the zip file have been extracted
+to the directory: `/home/DTaaS`.
+
+!!! tip
+    The path given here is for Linux OS.
+       It can be Windows compatible as well, for example: `C:\\DTaaS`. Make
+       sure to use this path and format in place of `/home/DTaaS` in this
+       guide.
+
+## Starting Portainer
+
+The GUI used to run the application and docker containers will be provided by
+[Portainer Community Edition](https://portainer.io). It is itself a Docker
+container that will create a website at `https://localhost:9443`, which will
+present a graphical interface for starting and stopping the application.
+
+You may follow
+[the official documentation for setting up a Portainer CE Server](https://docs.portainer.io/start/install-ce/server/docker)
+. Alternatively, open a terminal on your system (Terminal on Linux / MacOS,
+Powershell on Windows, etc) and copy the following commands into it:
+
+```bash
+docker volume create portainer_data
+docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:2.21.4
+```
+
+This will start the Portainer server on your system, which will host its
+dashboard at `https://localhost:9443`. Follow the
+[Initial Setup Guide](https://docs.portainer.io/start/install-ce/server/setup)
+to set up an administrator account for Portainer on your system.
+
+Portainer should now be set up on your system, and you can access the dashboard:
+
+![Portainer Admin Dashboard](./portainer_dashboard.png)
+
+!!! tip
+    The next time you wish to start the Portainer server, run
+       `docker start portainer`.
+
+## Configuration
+
+### Create User Workspace
+
+The existing filesystem for installation is setup for `user1`.
+A new filesystem directory needs to be created for the selected user.
+
+You may use your file explorer or an equivalent application to duplicate the
+`files/user1` directory and rename it as `files/username` where _username_ is
+the selected username registered on <https://gitlab.com>.
+
+ALternatively, you may execute the following commands from the top-level
+directory of the DTaaS project.
+
+```bash
+cp -R files/user1 files/username
+```
+
+### Creating the Portainer Stack
+
+![Portainer Stacks](./portainer_stacks.png)
+
+Portainer Stacks are equivalent to using `docker compose` commands to manage containers.
+
+1. Navigate to the _Stacks_ tab on the side panel, and click on the _Add Stack_ button.
+1. Name the Stack anything descriptive, for example: `dtaas-localhost`.
+1. Select the _Upload_ build method.
+1. Upload the compose file located at `deploy/docker/compose.local.yml`.
+1. Select the option to load variables from a .env file, and upload the file `deploy/docker/.env.local`.
+
+!!! tip
+    Sometimes the `.env.local` file does not show up in the file explorer. You
+    may fix this by selecting the option to show _All Files_ rather than those
+    with the extension _.env_.
+
+![Portainer ENV Editor](./portainer_env.PNG)
+
+The `.env.local` file contains environment variables that are used by the
+compose file. Portainer allows you to modify them as shown in the screenshot
+above, here is a summary:
+
+  | URL Path | Example Value | Explanation |
+  |:------------|:---------------|:---------------|
+  | DTAAS_DIR | '/home/Desktop/DTaaS' | Full path to the DTaaS directory. This is an absolute path with no trailing slash. |
+  | username1 | 'user1' | Your gitlab username |
+
+<!-- markdownlint-disable MD046 -->
+<!-- prettier-ignore -->
+!!! tip
+    Important points to note:
+
+    1. The path examples given here are for Linux OS.
+       These paths can be Windows OS compatible paths as well.
+    1. The client configuration file is located at `deploy/config/client/env.local.js`.
+       If you are following the guide to use HTTPS on localhost, edit the URLs in this file by replacing `http` with `https`.
+<!-- markdownlint-enable MD046 -->
+
+Once you have configured the environment variables, click on the button
+_Deploy the stack_.
+
+## Use
+
+The application will be accessible at:
+<http://localhost> from web browser.
+Sign in using your <https://gitlab.com> account.
+
+All the functionality of DTaaS should be available to you
+through the single page client now.
+
+## Limitations
+
+The [library microservice](../servers/lib/docker.md) is not
+included in the localhost installation scenario.
+
+## References
+
+Image sources:
+[Traefik logo](https://www.laub-home.de/wiki/Traefik_SSL_Reverse_Proxy_f%C3%BCr_Docker_Container),
+[ml-workspace](https://github.com/ml-tooling/ml-workspace),
+[reactjs](https://krify.co/about-reactjs/),
+[gitlab](https://gitlab.com)

docs/developer/github-actions.md

@@ -1,7 +1,7 @@
 # Secrets for Github Action
 
 The Github actions require the following secrets to be obtained
-from [docker hub](hub.docker.com):
+from [docker hub](https://hub.docker.com):
 
 | Secret Name | Explanation |
 |:---|:---|

mkdocs-github.yml

@@ -70,6 +70,7 @@ nav:
           - NPM: admin/servers/lib/npm.md
           - Docker: admin/servers/lib/docker.md
       - Guides:
+        - GUI Installation: admin/guides/localhost_portainer.md
         - Add user: admin/guides/add_user.md
         - Remove user: admin/guides/remove_user.md
         - Add Service: admin/guides/add_service.md
@@ -78,8 +79,9 @@ nav:
         - Common Assets: admin/guides/common_workspace_readonly.md
         - HTTP Mode: admin/guides/hosting_site_without_https.md
   - FAQ: FAQ.md
-  - Developer: 
-      - Developer Guide: developer/index.md 
+  - Developer:
+      - Developer Guide: developer/index.md
+      - GitHub Actions: developer/github-actions.md
       - System:
         - Architecture: developer/system/architecture.md
         - Current Status: developer/system/current-status.md

mkdocs.yml

@@ -70,6 +70,7 @@ nav:
           - NPM: admin/servers/lib/npm.md
           - Docker: admin/servers/lib/docker.md
       - Guides:
+        - GUI Installation: admin/guides/localhost_portainer.md
         - Add user: admin/guides/add_user.md
         - Remove user: admin/guides/remove_user.md
         - Add Service: admin/guides/add_service.md
@@ -78,8 +79,9 @@ nav:
         - Common Assets: admin/guides/common_workspace_readonly.md
         - HTTP Mode: admin/guides/hosting_site_without_https.md
   - FAQ: FAQ.md
-  - Developer: 
-      - Developer Guide: developer/index.md 
+  - Developer:
+      - Developer Guide: developer/index.md
+      - GitHub Actions: developer/github-actions.md
       - System:
         - Architecture: developer/system/architecture.md
         - Current Status: developer/system/current-status.md