Skip to content

Commit

Permalink
Moer documentation improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@nwmac
nwmac committed Jul 22, 2020
1 parent 208baa0 commit fff9924
Show file tree
Hide file tree
Showing 18 changed files with 540 additions and 120 deletions.
409 changes: 409 additions & 0 deletions deploy/kubernetes/console/README.md
View file

Large diffs are not rendered by default.

20 changes: 19 additions & 1 deletion website/deploy.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)"

Expand Down
14 changes: 12 additions & 2 deletions website/docs/deploy/all-in-one.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
58 changes: 58 additions & 0 deletions website/docs/deploy/cloud-foundry/cf-troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -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:
56 changes: 0 additions & 56 deletions website/docs/deploy/cloud-foundry.md → ...ocs/deploy/cloud-foundry/cloud-foundry.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
```
[
{
Expand Down
6 changes: 3 additions & 3 deletions ...te/docs/deploy/kubernetes/installation.md → website/docs/deploy/kubernetes/install.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.

31 changes: 30 additions & 1 deletion website/docs/deploy/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion website/docs/deploy/troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: troubleshooting
title: Troubleshooting
title: General Troubleshooting
sidebar_label: Troubleshooting
---

Expand Down
6 changes: 3 additions & 3 deletions website/docs/extensions/frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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)

12 changes: 1 addition & 11 deletions website/docs/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand All @@ -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).
Expand Down
Loading

0 comments on commit fff9924

Please sign in to comment.