Deployment description

Signed-off-by: Dennis Labordus <[email protected]>

Author: Dennis Labordus

DEPLOYMENT.md

@@ -0,0 +1,39 @@
+<!--
+SPDX-FileCopyrightText: 2021 Alliander N.V.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Deployment View
+
+Below is a global overview of the expected deployment of the CoMPAS Environment.
+
+![Deployment View](images/deployment-view.png)
+
+The engineer uses an internet browser to connect to the web application. The internet browser also sends
+REST Calls to the different back-end services. All request are going to the same base URL, for instance 
+http://localhost/ in the Docker Compose variant.
+
+The internet browser will first go through a reverse proxy that will first validate if the engineer is logged in.
+If not an SSO Provider is used log the engineer in. This SSO Provider also delivers a JSON Web Token (JWT) to be 
+used by the reverse proxy.
+
+Depending on the context root the reverse proxy send the request further to the container. The JWT is added as 
+authorization header to the requests to the containers. The JWT also contains the roles the engineer has.
+
+The container validates the JWT using a verification key. This is often an URL to the SSO Provider that returns 
+a JSON Web Key (Set) (JWK/JWKS). Also it uses the configured Path to retrieve the Roles/Groups.
+
+## Local Deployment
+
+- **Docker Compose**: Container Environment
+- **KeyCloak**: For the local deployment found in the GIT Repository we are using KeyCloak as an SSO Provider. 
+  All the users and roles are configured in KeyCloak.
+- **OpenResty**: As reverse proxy we are using a customized docker image of OpenResty. OpenResty verifies if the user 
+  is logged in and injects the JWT it retrieved from KeyCloak to the request going to the back-end services.
+
+## Amazon Cloud (AWS)
+
+- **Amazon EKS**: Container Environment?
+- **Amazon Cognito**: SSO Provider?
+- **AWS Elastic Load Balancing**: Reverse proxy?

INTEGRATION_TESTING.md

@@ -0,0 +1,42 @@
+<!--
+SPDX-FileCopyrightText: 2021 Alliander N.V.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Integration Testing
+
+To improve the quality of the application more beside the testing in the separate repositories we also created some integration
+tests to test all components together. The integration tests are executed against the Docker Compose version in this project.
+
+We are using the [Robot Framework](https://robotframework.org/) to execute the integration tests. For the Robot Framework we are
+using the [Browser Library](https://github.com/MarketSquare/robotframework-browser) to do the Web testing. this Library is based
+on [Playwright](https://playwright.dev/). All Integration Tests and data can be found in the directory 'integration-testing'.
+Output can be found in the directory 'target' is below commands and Github Actions are used.
+
+Some useful links:
+- [Robot Framework](https://robotframework.org/)
+- [Robot Framework User Guid](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html)
+- [Robot Framework BuildIn Keywords](https://robotframework.org/robotframework/latest/libraries/BuiltIn.html)
+- [Browser Library](https://github.com/MarketSquare/robotframework-browser)
+- [Browser Library Keywords](https://marketsquare.github.io/robotframework-browser/Browser.html)
+- [Playwright](https://playwright.dev/)
+- [Playwright Documentation](https://playwright.dev/docs/intro/)
+
+Some useful commands to execute the Robot Framework locally.  
+Please follow the instructions of [Robot Framework](https://robotframework.org/) to install the Framework.  
+And also follow the instruction of [Browser Library](https://github.com/MarketSquare/robotframework-browser) to install this needed library.
+
+```
+# Prefer to remove the target directory before starting.
+rm -r target
+
+# Normal run of all the test suites (with firefox, headless).
+robot -d target/firefox integration-testing/
+
+# Run of all the test suites (with firefox in presenter mode to better follow what happens).
+robot -d target/firefox -v browser:firefox -v enable_presenter_mode:true -v headless:false integration-testing/
+
+# Run of all the test suites (with chromium, headless), looks like chromium now only works headless. It crashs otherwise.
+robot -d target/chromium -v browser:chromium integration-testing/
+```

README.md

@@ -9,7 +9,9 @@ SPDX-License-Identifier: Apache-2.0
 [![Slack](https://raw.githubusercontent.com/com-pas/compas-architecture/master/public/LFEnergy-slack.svg)](http://lfenergy.slack.com/)
 
 # CoMPAS Deployment Repository
-Containing tools / configurations for deploying CoMPAS services.
+Containing tools / configurations for deploying CoMPAS services. For a deployment overview see [here](DEPLOYMENT.md)
+
+More about the integration tests being run against these Docker Compose environment can be found [here](INTEGRATION_TESTING.md)
 
 ## Docker Compose (BaseX)
 There is a pre configured [Docker Compose](compas/docker-compose-basex.yml) file, which starts all the given CoMPAS services.
@@ -104,40 +106,3 @@ These roles are assigned to certain users (see below).
 - **A SCD Reader**: A user with the role 'Read' only on the SCD Type.
   - Username: scd-reader
   - Password: reader
-
-## Integration Testing
-
-To improve the quality of the application more beside the testing in the separate repositories we also created some integration
-tests to test all components together. The integration tests are executed against the Docker Compose version in this project.
-
-We are using the [Robot Framework](https://robotframework.org/) to execute the integration tests. For the Robot Framework we are 
-using the [Browser Library](https://github.com/MarketSquare/robotframework-browser) to do the Web testing. this Library is based 
-on [Playwright](https://playwright.dev/). All Integration Tests and data can be found in the directory 'integration-testing'.
-Output can be found in the directory 'target' is below commands and Github Actions are used.
-
-Some useful links:
-- [Robot Framework](https://robotframework.org/)
-- [Robot Framework User Guid](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html)
-- [Robot Framework BuildIn Keywords](https://robotframework.org/robotframework/latest/libraries/BuiltIn.html)
-- [Browser Library](https://github.com/MarketSquare/robotframework-browser)
-- [Browser Library Keywords](https://marketsquare.github.io/robotframework-browser/Browser.html)
-- [Playwright](https://playwright.dev/)
-- [Playwright Documentation](https://playwright.dev/docs/intro/)
-
-Some useful commands to execute the Robot Framework locally.  
-Please follow the instructions of [Robot Framework](https://robotframework.org/) to install the Framework.  
-And also follow the instruction of [Browser Library](https://github.com/MarketSquare/robotframework-browser) to install this needed library.
-
-```
-# Prefer to remove the target directory before starting.
-rm -r target
-
-# Normal run of all the test suites (with firefox, headless).
-robot -d target/firefox integration-testing/
-
-# Run of all the test suites (with firefox in presenter mode to better follow what happens).
-robot -d target/firefox -v browser:firefox -v enable_presenter_mode:true -v headless:false integration-testing/
-
-# Run of all the test suites (with chromium, headless), looks like chromium now only works headless. It crashs otherwise.
-robot -d target/chromium -v browser:chromium integration-testing/
-```

images/deployment-view.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-09-07T09:10:37.842Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="lYk3ZGuue9Wm70Cj9oxD" version="20.2.8" type="device"><diagram name="Page-1" id="c37626ed-c26b-45fb-9056-f9ebc6bb27b6">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</diagram></mxfile>