Moer documentation improvements

cloudfoundry · richard-cox · Aug 7, 2020 · Jul 13, 2020 · Jul 13, 2020 · Jul 20, 2020
commit fff9924511da007dc10201781c452f6acc6cdd2f
diff --git a/deploy/kubernetes/console/README.md b/deploy/kubernetes/console/README.md
diff --git a/website/deploy.sh b/website/deploy.sh
@@ -9,7 +9,25 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
 
 pushd $DIR > /dev/null
 echo "Building website ..."
-#npm run build
+
+# Copy helm chart readme
+cat << EOF > ./docs/deploy/kubernetes/install.md
+---
+id: helm-installation
+title: Deploying Using Helm
+sidebar_label: Deploy using Helm 
+---
+EOF
+
+# Concatentate the helm chart readme file
+cat ${DIR}/../deploy/kubernetes/console/README.md >> ./docs/deploy/kubernetes/install.md
+npm run build
+
+
+# Build only
+if [ "$1" == "-b" ]; then
+  exit 0
+fi
 
 msg="Website update: $(date)"
 

diff --git a/website/docs/deploy/all-in-one.md b/website/docs/deploy/all-in-one.md
@@ -8,9 +8,19 @@ The all-in-one container sets up the Stratos components in a single container.
 
 ## Requirements:
 
-You will need to have installed Docker, see:
+You will need to have installed Docker, see [Docker Installation Documentation](https://docs.docker.com/engine/installation/).
 
-* [Docker](https://docs.docker.com/engine/installation/)
+## Quick Start
+
+Run Stratos in Docker locally:
+
+```
+$ docker run -p 4443:443 splatform/stratos:latest 
+```
+
+Once that has finished, you can then access Stratos by visiting [https://localhost:4443](https://localhost:4443).
+
+You can configure a local admin account and set the password for future logins.
 
 ## Note regarding the Stratos Session Store Secret
 

diff --git a/website/docs/deploy/cloud-foundry/cf-troubleshooting.md b/website/docs/deploy/cloud-foundry/cf-troubleshooting.md
@@ -0,0 +1,58 @@
+---
+title: Troubleshooting Cloud Foundry Deployment
+sidebar_label: Troubleshooting
+---
+
+## Creating logs for recent deployments
+To create a log file of the push
+```
+cf push | tee cfpush.log
+```
+
+To create a log file of recent console output
+```
+cf logs console --recent | tee cfconsole.log
+```
+>**NOTE** If the name of the application has been changed from `console` in the manifest file please also change the name in the logs statement
+
+## Turning on backend debugging logs
+
+The `LOG_LEVEL` environment variable controls the backend logs 
+
+```
+cf set-env console LOG_LEVEL debug 
+cf restart console
+cf logs console
+```
+
+would output more debugging output such as
+
+```
+  2018-10-24T14:47:36.91+0200 [RTR/1] OUT console.my.domain - [2018-10-24T12:47:36.850+0000] "GET /pp/v1/-o1F0L956QhAIK7R56Uc1lMh5L4/apps/3ddc0bc6-a645-4449-9d1b-6fe86146cf61/ssh/0 HTTP/1.1" 500 0 0 "-" "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0" "10.228.194.8:42182" "192.168.35.91:61044" x_forwarded_for:"10.228.194.8" x_forwarded_proto:"https" vcap_request_id:"182dddeb-d877-4d58-45f7-0bd886d1caf6" response_time:0.066925325 app_id:"0ba408ef-d0e6-4ab8-96bb-0bc078b8d8fb" app_index:"0" x_b3_traceid:"d166622a0d612fea" x_b3_spanid:"d166622a0d612fea" x_b3_parentspanid:"-"
+   2018-10-24T14:47:36.91+0200 [RTR/1] OUT 
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] sessionCleanupMiddleware                     
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] errorLoggingMiddleware                       
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT INFO[Wed Oct 24 12:47:36 UTC 2018] Not redirecting this request                 
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSession                                   
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSessionValue                              
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSession                                   
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] setStaticContentHeadersMiddleware            
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] urlCheckMiddleware                           
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] sessionMiddleware                            
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSessionValue                              
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSession                                   
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] xsrfMiddleware                               
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] GetCNSIRecord                                
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] Find                                         
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] decryptToken                                 
+   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] Decrypt                                      
+   [...]
+```
+
+## Application Security Groups
+
+If you have problems when deploying Stratos as a Cloud Foundry application, check that the Application Security Group you have will allow Stratos to communicate with the Cloud Foundry API.
+
+For information on the default ASGs, see [here](https://docs.cloudfoundry.org/concepts/asg.html#default-asg).
+
+To configure a new ASG for the organization and space that are using Stratos, first create a new ASG definition, for example:
diff --git a/website/docs/deploy/cloud-foundry.md → ...ocs/deploy/cloud-foundry/cloud-foundry.md b/website/docs/deploy/cloud-foundry.md → ...ocs/deploy/cloud-foundry/cloud-foundry.md
@@ -161,62 +161,6 @@ When SSO Login is enabled, Stratos will also auto-connect to the Cloud Foundry i
 
 For more information - see [Single-Sign On](../guides/admin/sso).
 
-## Troubleshooting
-
-### Creating logs for recent deployments
-To create a log file of the push
-```
-cf push | tee cfpush.log
-```
-
-To create a log file of recent console output
-```
-cf logs console --recent | tee cfconsole.log
-```
->**NOTE** If the name of the application has been changed from `console` in the manifest file please also change the name in the logs statement
-
-### Turning on backend debugging logs
-
-The `LOG_LEVEL` environment variable controls the backend logs 
-
-```
-cf set-env console LOG_LEVEL debug 
-cf restart console
-cf logs console
-```
-
-would output more debugging output such as
-
-```
-  2018-10-24T14:47:36.91+0200 [RTR/1] OUT console.my.domain - [2018-10-24T12:47:36.850+0000] "GET /pp/v1/-o1F0L956QhAIK7R56Uc1lMh5L4/apps/3ddc0bc6-a645-4449-9d1b-6fe86146cf61/ssh/0 HTTP/1.1" 500 0 0 "-" "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0" "10.228.194.8:42182" "192.168.35.91:61044" x_forwarded_for:"10.228.194.8" x_forwarded_proto:"https" vcap_request_id:"182dddeb-d877-4d58-45f7-0bd886d1caf6" response_time:0.066925325 app_id:"0ba408ef-d0e6-4ab8-96bb-0bc078b8d8fb" app_index:"0" x_b3_traceid:"d166622a0d612fea" x_b3_spanid:"d166622a0d612fea" x_b3_parentspanid:"-"
-   2018-10-24T14:47:36.91+0200 [RTR/1] OUT 
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] sessionCleanupMiddleware                     
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] errorLoggingMiddleware                       
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT INFO[Wed Oct 24 12:47:36 UTC 2018] Not redirecting this request                 
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSession                                   
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSessionValue                              
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSession                                   
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] setStaticContentHeadersMiddleware            
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] urlCheckMiddleware                           
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] sessionMiddleware                            
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSessionValue                              
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] getSession                                   
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] xsrfMiddleware                               
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] GetCNSIRecord                                
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] Find                                         
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] decryptToken                                 
-   2018-10-24T14:47:36.85+0200 [APP/PROC/WEB/0] OUT DEBU[Wed Oct 24 12:47:36 UTC 2018] Decrypt                                      
-   [...]
-```
-
-### Application Security Groups
-
-If you have problems when deploying Stratos UI as a Cloud Foundry application, check that the Application Security Group you have will allow Stratos to communicate with the Cloud Foundry API.
-
-For information on the default ASGs, see [here](https://docs.cloudfoundry.org/concepts/asg.html#default-asg).
-
-To configure a new ASG for the organization and space that are using Stratos, first create a new ASG definition, for example:
-
 ```
 [
    {

diff --git a/...te/docs/deploy/kubernetes/installation.md → website/docs/deploy/kubernetes/install.md b/...te/docs/deploy/kubernetes/installation.md → website/docs/deploy/kubernetes/install.md
@@ -1,8 +1,9 @@
 ---
 id: helm-installation
-title: Stratos Installation
+title: Deploying Using Helm
 sidebar_label: Deploy using Helm 
 ---
+# Stratos
 
 Stratos is an Open Source Web-based Management console for Cloud Foundry. It allows users and administrators to both manage applications running in the Cloud Foundry cluster and perform cluster management tasks.
 
@@ -260,7 +261,7 @@ You will also need to specify:
 - `console.mariadb.port` as the port of the external MariaDB database server (defaults to 3306)
 - `console.mariadb.tls` as the TLS mode (default is `false,` use `true` for a TLS connection to the database server)
 - `console.mariadb.database` as the name of the database
-- `console.mariadb.user` as the username to connect to the database server
+- `console.mariadb.user` as the username to connect to the database server
 - `console.mariadb.userPassword` as the password to connect to the database server
 
 When using an external database server, Stratos expects that you have:
@@ -411,4 +412,3 @@ kubectl create -f storageclass.yaml
 ```
 
 See [Storage Class documentation](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) for more information.
-
diff --git a/website/docs/deploy/overview.md b/website/docs/deploy/overview.md
@@ -12,4 +12,33 @@ Stratos can be deployed in the following environments:
 
 > Note: that not all features are enabled in every environment - the Kubernetes deployment supports all features, but Cloud Foundry and Docker deployments do not support some features.
 
-> Note: Some features are marked as 'Tech Preview' and are only available if tech preview features are enabled when deploying.
+> Note: Some features are marked as 'Tech Preview' and are only available if tech preview features are enabled when deploying.
+
+## Deployed in Cloud Foundry as an application
+
+In this case, Stratos is deployed in a manner optimized for the management of a single Cloud Foundry instance. The 'Endpoints Dashboard' that allows multiple Cloud Foundry endpoints to be registered is not deployed. An extra component is deployed that detects that the Console is running as Cloud Foundry which does the following:
+
+- Automatically detects the Cloud Foundry endpoint and located the UAA Endpoint to use for authentication
+- Authenticates directly against the UAA for the Clound Foundry where the Console is deployed and assumes that Cloud Foundry admins are also Console admins (the UAA Scope 'cloud_controller.admin' is used to identify admins)
+- Uses a SQLite database rather than Postgres
+- Automatically connects to the Cloud Foundry endpoint when a user logs in to simplify the user flow when using the Console in this case
+
+In this case, the front-end web application static resources are served by the API Server back-end rather than a separate web server.
+
+By defaut, a non-persistent SQLite database is used - by automatically registering the cloud foundry endpoint and connecting to it on login, all data stored in the database can be treated as ephimeral, since it will be re-created next time a user logs in. Cloud Foundry Session Affinity is used to ensure that when scaling up the Console Application to multiple instances, the user is also directed to the instance which will know about them and their endpoints (since each Application instance will have its own local SQLite store).
+
+Alternatively, Stratos can be configured [with a persistent Cloud Foundry database service](deploy/cloud-foundry/db-migration), which enables features requiring persistence such as user favorites.
+
+## Deployed in Kubernetes
+
+In this case, a Helm chart is used to deploy the Console into a Kubernetes environment.
+
+At the outer-level there are two services - the external service that provides the Console itself and a private service that provides a Postgres DB to the Console service.
+
+The Console service is provided by a deployment consisting of two containers, one providing the static front-end web application resources, served by an nginx instance, the other providing the API Server back-end.
+
+## Deployed in Docker using a single container
+
+In this case, a single Docker image is run in a container that hosts all services together. SQLite is used as the database, so any endpoint metadata registered is lost when the container is destroyed.
+
+This deployment is recommended only for trying out the Console and for development.
diff --git a/website/docs/deploy/troubleshooting.md b/website/docs/deploy/troubleshooting.md
@@ -1,6 +1,6 @@
 ---
 id: troubleshooting
-title: Troubleshooting
+title: General Troubleshooting
 sidebar_label: Troubleshooting 
 ---
 

diff --git a/website/docs/extensions/frontend.md b/website/docs/extensions/frontend.md
@@ -79,7 +79,7 @@ Tabs can be added to the following views in Stratos:
 
 For example:
 
-![Example Application tab extension](images/extensions/app-tab-example.png)
+![Example Application tab extension](../images/extensions/app-tab-example.png)
 
 The approach for all of these is the same:
 
@@ -120,7 +120,7 @@ Actions can be added to the following views in Stratos:
 
 An action is a icon button that appears at the top-right of a View. For example:
 
-![Example Application action extension](images/extensions/appwall-action-example.png)
+![Example Application action extension](../images/extensions/appwall-action-example.png)
 
 The approach for all of these is the same:
 
@@ -267,5 +267,5 @@ export class CustomModule { }
 
 You should now be able to run Stratos locally and see this new tab on the application page for an application - as illustrated below:
 
-![Example tab extension](images/extensions/tab-example.png)
+![Example tab extension](../images/extensions/tab-example.png)
 
diff --git a/website/docs/introduction.md b/website/docs/introduction.md
@@ -10,7 +10,7 @@ For Cloud Foundry, it allows users and administrators to both manage application
 
 For Kubernetes, it provides Developers with views of their Kubernetes resources, the ability to vide and deploy Helm Charts and view Workloads.
 
-![Stratos Application view](images/screenshots/app-summary.png)
+![Stratos Application view](../images/screenshots/app-summary.png)
 
 ## Quick Start
 
@@ -37,12 +37,8 @@ Please see our [Troubleshooting](guides/troubleshooting/troubleshooting) page.
 
 ## Further Reading
 
-Take a look at the [Feature Set](features.md) for details on the feature set that Stratos provides.
-
 Get an [Overview](overview.md) of Stratos, its components and the different ways in which it can be deployed.
 
-Take a look at the [Development Roadmap](roadmap.md) to see where we are heading. We update our status page each week to summarize what we are working on - see the [Status Page](status_updates.md).
-
 Browse through features and issues in the project's [issues](https://github.com/cloudfoundry/stratos/issues) page.
 
 What kind of code is in Stratos? We've integrated [Code Climate](https://codeclimate.com) for some code quality and maintainability metrics. Take a stroll around the [project page](https://codeclimate.com/github/cloudfoundry/stratos)
@@ -59,12 +55,6 @@ We have a channel (#stratos) on the Cloud Foundy Slack where you can ask questio
 
 You can join the Cloud Foundry Slack here - https://slack.cloudfoundry.org/  - and then join the #stratos channel.
 
-## Acknowledgements
-
-Tested with Browserstack
-
-<a href="https://www.browserstack.com"><img width="240px" src="docs/images/Browserstack-logo.svg" alt="Browserstack" /></a>
-
 ## License
 
 The work done has been licensed under Apache License 2.0. The license file can be found [here](LICENSE).