Merge pull request #87 from com-pas/deployment-view

Deployment Overview of the Docker Compose

Author: pascalwilbrink

.reuse/dep5

@@ -0,0 +1,8 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: compas-deployment
+Upstream-Contact: Sander Jansen <[email protected]>
+Source: https://github.com/com-pas/compas-deployment
+
+Files: images/*
+Copyright: 2022 Alliander N.V.
+License: Apache-2.0

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](https://aws.amazon.com/eks/)**: Container Environment?
+- **[Amazon Cognito](https://aws.amazon.com/cognito/)**: SSO Provider?
+- **[AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/)**: 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-08T05:34:50.511Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="kRcnI-EVh7d9fnGrXaFf" version="20.2.8" type="device"><diagram name="Page-1" id="c37626ed-c26b-45fb-9056-f9ebc6bb27b6">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</diagram></mxfile>