From cd4498769a8688e1b6473dbe56859fc44b687f1a Mon Sep 17 00:00:00 2001 From: Richard Cox Date: Tue, 28 Jul 2020 10:48:24 +0100 Subject: [PATCH 01/14] Ensure filename/no filename text in connect by file dialog is aligned (#4474) - needs porting back --- .../src/shared/components/file-input/file-input.component.scss | 1 + 1 file changed, 1 insertion(+) diff --git a/src/frontend/packages/core/src/shared/components/file-input/file-input.component.scss b/src/frontend/packages/core/src/shared/components/file-input/file-input.component.scss index b1417ebcc8..aa0e1b908a 100644 --- a/src/frontend/packages/core/src/shared/components/file-input/file-input.component.scss +++ b/src/frontend/packages/core/src/shared/components/file-input/file-input.component.scss @@ -7,6 +7,7 @@ pointer-events: none; } &__field { + align-items: center; display: flex; } &__input { From f62768872eeea15ca0bd7f1657bb71ce54591738 Mon Sep 17 00:00:00 2001 From: Richard Cox Date: Fri, 7 Aug 2020 16:20:52 +0100 Subject: [PATCH 02/14] Add typed entity access and `custom-src` removal to change log (#4496) --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ce74d5c42f..25b531ccc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ This release contains a number of fixes and improvements: **Improvements:** +- Extensions: Allow typed access to store entities and their actions [\#4494](https://github.com/cloudfoundry/stratos/issues/4494) - Extensions: Remove the need for symlinks and improve the build process [\#4472](https://github.com/cloudfoundry/stratos/issues/4472) - Extensions: Allow Themes to be published and installed to/from npm [\#4471](https://github.com/cloudfoundry/stratos/issues/4471) - Extensions: Move to extensions and themes to be packages [\#4470](https://github.com/cloudfoundry/stratos/issues/4470) @@ -60,6 +61,9 @@ This release contains a number of fixes and improvements: **Breaking Changes:** +- **Customizations in `custom-src` are now npm packages** + + Stratos customizations were previously in `./custom-src` and included in the build via symlinks. These customizations have now moved into local npm packages located in `./src/frontend/packages`. For more details please see our customization documentation at `./website/docs/extensions/introduction.md` or `https://stratos.app/docs/extensions/introduction`. There you will also find instructions on migrating to npm packages and a tool to help automate most of the process. - **Kubernetes: Upgrade only possible from version 3.0.0 or later** When deploying into Kubernetes using Helm and upgrading from an earlier version of Stratos using `helm upgrade`, upgrade is **only** supported from version 3.0.0 or later. If you are using an earlier version, first upgrade to version 3.x before then upgrading to the latest version. From d7102e7771b78be66d4d042086671c1d5b22066d Mon Sep 17 00:00:00 2001 From: Veerapuram Varadhan Date: Fri, 7 Aug 2020 21:57:32 +0530 Subject: [PATCH 03/14] Fixes #4335: Create Stratos static web site with better documentation (#4446) * Fixes #4335: Create Stratos static web site with better documentation structure using docusaurus. Initial commit. * 1) Re-organize some more existing doc files. 2) Re-organize links in the doc file to refer to the new document hierarchy. * Landing Page WIP * Documentation tweaks * Use better action names * More visual improvements to landing page * More doc and landing page improvements * Remove publish workflow for now * Typo fix * Moer documentation improvements * Remove extra title from helm doc * Fix script when used from npm * Improve layout on mobile devices * More documentation improvements * Fix typo * Merge downstream (#4441) * Merge src/frontend from downstream * Merge src/jetstream from jetstream * Remove examples/custom-src * Merge deploy from downstream Does not include changes to - deploy/all-in-one/* - deploy/aio-entrypoint.sh - deploy/Dockerfile.all-in-one * Merge build from downstream * Add missing merge items from deploy * Updates to package-lock * Remove fdescribe * Fix e2e core tests * Remove favicon from packages/core/src * Changes following review * Show all favorites for an endpoint favorite if there is only one (#4440) * Show all favorites for the endpoint favorite if there is only one * Missing changes * Merge downstream - JSON Viewer with dark mode & Header Fixes (#4444) * Fix json-viewer dark mode * Fix profile page and side nav top position following header diet - Fix side nav top position - Update fix for profile page to also work in non-desktop mode * Fix issues with tests not running if build upload fails (#4453) * Fix issues with tests not running if build upload fails * Fix script * One more fix for script * Fix white space at start of file * Improve autoscaler e2e logging (#4456) * Improve autoscaler e2e logging - it looks like the AS returns scaling events 1-2 mins after they occur, which is too late for the test - add additional logging to print out event table data in case of alternative events being raised - fix logging if wait for events times out - add hint in later test that depends on AS scaling event * Ensure only the schedule rule results in scaling events * Fix check-e2e-pr.sh for pr's from other repos (#4459) - switch from TRAVIS_PULL_REQUEST_SLUG to TRAVIS_REPO_SLUG * Convert Client Secret Input Fields to `password` (#4455) * Insecure tlsv10 and tlsv11 ciphers in Stratos UI, bsc#1173295 (#411) (#4460) Co-authored-by: Michal Jura * [Security] Bump codecov from 3.7.0 to 3.7.1 (#4457) Bumps [codecov](https://github.com/codecov/codecov-node) from 3.7.0 to 3.7.1. **This update includes a security fix.** - [Release notes](https://github.com/codecov/codecov-node/releases) - [Commits](https://github.com/codecov/codecov-node/compare/v3.7.0...v3.7.1) Signed-off-by: dependabot-preview[bot] Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com> * Bump lodash from 4.17.15 to 4.17.19 (#4452) Bumps [lodash](https://github.com/lodash/lodash) from 4.17.15 to 4.17.19. - [Release notes](https://github.com/lodash/lodash/releases) - [Commits](https://github.com/lodash/lodash/compare/4.17.15...4.17.19) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Website update: Wed 22 Jul 2020 21:55:00 BST * Website update: Wed 22 Jul 2020 21:56:45 BST * Website update: Wed 22 Jul 2020 21:58:22 BST * Remove dist * FIx deploy script to remove old files * Moer tidy ups * Add CNAME file when publishing * Add talks doc * * Fix broken links due to reorganization of documents * Move Troubleshooting content from cloud-foundry deployment doc to cf-troubleshooting * * Fix Getting Started broken link in page footer * Only publish if there are website changes * Remove old doc * Publish website on merge * * Review comments fix * Fix broken link to an image in frontend extensions doc * Final tweaks Co-authored-by: Neil MacDougall Co-authored-by: Neil MacDougall Co-authored-by: Richard Cox Co-authored-by: Neil MacDougall Co-authored-by: Michal Jura Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Richard Cox --- .cfignore | 1 + .codeclimate.yml | 3 +- .github/workflows/documentation.yml | 66 + .gitignore | 3 + CONTRIBUTING.md | 10 +- README.md | 2 +- deploy/README.md | 8 - deploy/cloud-foundry/README.md | 314 - deploy/kubernetes/console/README.md | 3 +- docs/contributing.md | 85 - docs/developers-guide.md | 294 - docs/i18n.md | 3 - docs/index.html | 1 - docs/issue_template.md | 5 +- docs/overview.md | 64 - docs/roadmap.md | 39 - index.yaml | 76 - website/.gitignore | 23 + website/README.md | 40 + website/babel.config.js | 3 + website/deploy.sh | 101 + .../docs/advanced}/bosh-metrics.md | 5 +- .../docs/advanced}/invite-user-guide.md | 15 +- {docs => website/docs/advanced}/sso.md | 5 +- {docs => website/docs/deploy}/access.md | 6 +- .../docs/deploy/all-in-one.md | 20 +- .../cloud-foundry/cf-troubleshooting.md | 157 + .../deploy/cloud-foundry/cloud-foundry.md | 162 + .../docs/deploy/cloud-foundry/db-migration.md | 8 +- .../docs/deploy/kubernetes.md | 8 +- website/docs/deploy/kubernetes/install.md | 413 + website/docs/deploy/overview.md | 44 + .../docs/deploy}/troubleshooting.md | 8 +- website/docs/developer/backend.md | 124 + website/docs/developer/contributing.md | 162 + .../developer}/developers-guide-e2e-tests.md | 14 +- .../developer}/developers-guide-env-tech.md | 6 +- website/docs/developer/frontend-tests.md | 73 + website/docs/developer/frontend.md | 90 + website/docs/developer/introduction.md | 38 + .../docs/extensions/backend.md | 5 +- .../docs/extensions}/customizing.md | 45 +- .../docs/extensions/frontend.md | 59 +- website/docs/extensions/introduction.md | 5 + website/docs/extensions/theming.md | 14 + website/docs/extensions/v4-migration.md | 30 + website/docs/introduction.md | 63 + website/docs/license.md | 184 + website/docs/overview.md | 29 + website/docs/talks.md | 13 + website/docusaurus.config.js | 96 + website/package-lock.json | 13192 ++++++++++++++++ website/package.json | 30 + website/sidebars.js | 55 + website/src/css/custom.css | 191 + website/src/pages/index.js | 176 + website/src/pages/styles.module.css | 37 + website/static/.nojekyll | 0 .../static}/images/Browserstack-logo.svg | 0 .../images/extensions/app-tab-example.png | Bin .../extensions/appwall-action-example.png | Bin .../static}/images/extensions/tab-example.png | Bin .../static}/images/high-level-arch.png | Bin .../images/screenshots/app-summary.png | Bin website/static/img/cloudfoundry.png | Bin 0 -> 5301 bytes website/static/img/deploy.svg | 1 + website/static/img/easy.svg | 1 + website/static/img/extend.svg | 1 + website/static/img/favicon.ico | Bin 0 -> 15086 bytes website/static/img/kubernetes.svg | 84 + website/static/img/logo.png | Bin 0 -> 93628 bytes website/static/img/logo.svg | 1 + website/static/img/multi-cluster.svg | 3 + website/static/img/open-source.svg | 1 + website/static/img/screens/cf-app.png | Bin 0 -> 67519 bytes website/static/img/screens/endpoints.png | Bin 0 -> 33521 bytes website/static/img/screens/kube-graph.png | Bin 0 -> 63442 bytes 77 files changed, 15827 insertions(+), 991 deletions(-) create mode 100644 .github/workflows/documentation.yml delete mode 100644 deploy/README.md delete mode 100644 deploy/cloud-foundry/README.md delete mode 100644 docs/contributing.md delete mode 100644 docs/developers-guide.md delete mode 100644 docs/i18n.md delete mode 100644 docs/index.html delete mode 100644 docs/overview.md delete mode 100644 docs/roadmap.md delete mode 100755 index.yaml create mode 100644 website/.gitignore create mode 100644 website/README.md create mode 100644 website/babel.config.js create mode 100755 website/deploy.sh rename {docs => website/docs/advanced}/bosh-metrics.md (98%) rename {docs => website/docs/advanced}/invite-user-guide.md (92%) rename {docs => website/docs/advanced}/sso.md (96%) rename {docs => website/docs/deploy}/access.md (97%) rename deploy/all-in-one/README.md => website/docs/deploy/all-in-one.md (91%) create mode 100644 website/docs/deploy/cloud-foundry/cf-troubleshooting.md create mode 100644 website/docs/deploy/cloud-foundry/cloud-foundry.md rename deploy/cloud-foundry/db-migration/README.md => website/docs/deploy/cloud-foundry/db-migration.md (90%) rename deploy/kubernetes/README.md => website/docs/deploy/kubernetes.md (80%) create mode 100644 website/docs/deploy/kubernetes/install.md create mode 100644 website/docs/deploy/overview.md rename {docs => website/docs/deploy}/troubleshooting.md (78%) create mode 100644 website/docs/developer/backend.md create mode 100644 website/docs/developer/contributing.md rename {docs => website/docs/developer}/developers-guide-e2e-tests.md (90%) rename {docs => website/docs/developer}/developers-guide-env-tech.md (98%) create mode 100644 website/docs/developer/frontend-tests.md create mode 100644 website/docs/developer/frontend.md create mode 100644 website/docs/developer/introduction.md rename docs/backend-plugins.md => website/docs/extensions/backend.md (98%) rename {docs => website/docs/extensions}/customizing.md (77%) rename docs/extensions.md => website/docs/extensions/frontend.md (81%) create mode 100644 website/docs/extensions/introduction.md create mode 100644 website/docs/extensions/theming.md create mode 100644 website/docs/extensions/v4-migration.md create mode 100644 website/docs/introduction.md create mode 100644 website/docs/license.md create mode 100644 website/docs/overview.md create mode 100644 website/docs/talks.md create mode 100644 website/docusaurus.config.js create mode 100644 website/package-lock.json create mode 100644 website/package.json create mode 100644 website/sidebars.js create mode 100644 website/src/css/custom.css create mode 100644 website/src/pages/index.js create mode 100644 website/src/pages/styles.module.css create mode 100644 website/static/.nojekyll rename {docs => website/static}/images/Browserstack-logo.svg (100%) rename {docs => website/static}/images/extensions/app-tab-example.png (100%) rename {docs => website/static}/images/extensions/appwall-action-example.png (100%) rename {docs => website/static}/images/extensions/tab-example.png (100%) rename {docs => website/static}/images/high-level-arch.png (100%) rename {docs => website/static}/images/screenshots/app-summary.png (100%) create mode 100644 website/static/img/cloudfoundry.png create mode 100644 website/static/img/deploy.svg create mode 100644 website/static/img/easy.svg create mode 100644 website/static/img/extend.svg create mode 100644 website/static/img/favicon.ico create mode 100644 website/static/img/kubernetes.svg create mode 100644 website/static/img/logo.png create mode 100644 website/static/img/logo.svg create mode 100644 website/static/img/multi-cluster.svg create mode 100644 website/static/img/open-source.svg create mode 100644 website/static/img/screens/cf-app.png create mode 100644 website/static/img/screens/endpoints.png create mode 100644 website/static/img/screens/kube-graph.png diff --git a/.cfignore b/.cfignore index 21c16f20e7..92be10a235 100644 --- a/.cfignore +++ b/.cfignore @@ -21,3 +21,4 @@ deploy/uaa/ docs/ build/dev_config.json e2e-reports/ +website/ diff --git a/.codeclimate.yml b/.codeclimate.yml index 801ada6c4e..5650724125 100644 --- a/.codeclimate.yml +++ b/.codeclimate.yml @@ -28,4 +28,5 @@ exclude_patterns: - "**/vendor/" - "**/*.d.ts" - "**/__vendor/" -- "**/*_test.go" \ No newline at end of file +- "**/*_test.go" +- "website/" \ No newline at end of file diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000000..e99ddf7e80 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,66 @@ +name: documentation + +on: + pull_request: + branches: [master] + push: + branches: [master] + +jobs: + build-docs: + if: github.event_name != 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-node@v1 + with: + node-version: '12.x' + - name: Test Build + run: | + cd website + if [ -e yarn.lock ]; then + yarn install --frozen-lockfile + elif [ -e package-lock.json ]; then + npm ci + else + npm i + fi + npm run build + publish-docs: + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-node@v1 + with: + node-version: '12.x' + - name: Add key to allow access to repository + env: + SSH_AUTH_SOCK: /tmp/ssh_agent.sock + run: | + mkdir -p ~/.ssh + ssh-keyscan github.com >> ~/.ssh/known_hosts + echo "${{ secrets.GH_PAGES_DEPLOY }}" > ~/.ssh/id_rsa + chmod 600 ~/.ssh/id_rsa + cat <> ~/.ssh/config + Host github.com + HostName github.com + IdentityFile ~/.ssh/id_rsa + EOT + - name: Release to GitHub Pages + env: + USE_SSH: true + GIT_USER: git + run: | + cd website + git config --global user.email "actions@gihub.com" + git config --global user.name "gh-actions" + if [ -e yarn.lock ]; then + yarn install --frozen-lockfile + elif [ -e package-lock.json ]; then + npm ci + else + npm i + fi + echo "Deploying web site... hang tight" + ./deploy.sh \ No newline at end of file diff --git a/.gitignore b/.gitignore index 6b930df0a4..b4aff53859 100644 --- a/.gitignore +++ b/.gitignore @@ -120,3 +120,6 @@ stratos-frontend-prebuild.zip src/frontend/assets src/frontend/sass go-vendor-*.tgz + +website/build +website/site-dist \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ffe5499d4..6d081d6326 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ -# Contributing to Stratos UI +# Contributing to Stratos -Stratos UI is an open project and welcomes contributions. These guidelines are provided to help you understand how the project works and to make contributing smooth and fun for everybody involved. +Stratos is an open project and welcomes contributions. These guidelines are provided to help you understand how the project works and to make contributing smooth and fun for everybody involved. There are two main forms of contribution: reporting issues and performing code changes. ## Reporting Issues -If you find a problem with Stratos UI, report it using [GitHub issues](https://github.com/cloudfoundry/stratos/issues/new). +If you find a problem with Stratos, report it using [GitHub issues](https://github.com/cloudfoundry/stratos/issues/new). Before reporting a new issue, please take a moment to check whether it has already been reported [here](https://github.com/cloudfoundry/stratos/issues). If this is the case, please: @@ -29,7 +29,7 @@ This information will help to determine the cause and prepare a fix as fast as p ## Code Changes Code contributions come in various forms and sizes, from simple bug fixes to implementation -of new features. Before making any non-trivial change, get in touch with the Stratos UI developers first. This can prevent wasted effort later. +of new features. Before making any non-trivial change, get in touch with the Stratos developers first. This can prevent wasted effort later. To send your code change, use GitHub pull requests. The workflow is as follows: @@ -43,7 +43,7 @@ To send your code change, use GitHub pull requests. The workflow is as follows: 1. Publish the branch and create a pull request. - 1. Stratos UI developers will review your change and possibly point out issues. + 1. Stratos developers will review your change and possibly point out issues. Adapt the code under their guidance until all issues are resolved. 1. Finally, the pull request will get merged or rejected. diff --git a/README.md b/README.md index 397d3aaabd..a234c26d99 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Take a look at the [Feature Set](docs/features.md) for details on the feature se Get an [Overview](docs/overview.md) of Stratos, its components and the different ways in which it can be deployed. -Take a look at the [Development Roadmap](docs/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](docs/status_updates.md). +Take a look at the [Development Roadmap](docs/roadmap.md) to see where we are heading. Browse through features and issues in the project's [issues](https://github.com/cloudfoundry/stratos/issues) page. diff --git a/deploy/README.md b/deploy/README.md deleted file mode 100644 index cc7e9ed093..0000000000 --- a/deploy/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Deploying Stratos - -Stratos can be deployed in the following environments: - -1. Cloud Foundry, as an application. See [guide](cloud-foundry) -2. Kubernetes, using a Helm chart. See [guide](kubernetes) -3. Docker, single container deploying all components. See [guide](all-in-one) - diff --git a/deploy/cloud-foundry/README.md b/deploy/cloud-foundry/README.md deleted file mode 100644 index d06e09234e..0000000000 --- a/deploy/cloud-foundry/README.md +++ /dev/null @@ -1,314 +0,0 @@ -# Deploying as a Cloud Foundry Application - -## Deployment Steps - -The quickest way to install Stratos is to deploy it as a Cloud Foundry application. - -You can do it in two ways: - -1. [Deploy Stratos from source](#Deploy-Stratos-from-source) -1. [Deploy Stratos from docker image](#Deploy-Stratos-from-docker-image) - -You will then be able to open a web browser and navigate to the console URL: - -`https://console.` - -Where `` is the default domain configured for your Cloud Foundry cluster. - -To login use the following credentials detailed [here](../../docs/access.md). - -If you run into issues, please refer to the [Troubleshooting Guide](#troubleshooting) below. - -> The console will pre-configure the host Cloud Foundry endpoint. No other CF instance should be registered unless the instructions in - the section [Associate Cloud Foundry database service](#Associate-Cloud-Foundry-database-service) are followed. - All other deployment methods (helm, docker all-in-one, etc) allow the registration of multiple CF instances by default. - -Note: - -1. You need the cf CLI command line tool installed and available on the path. -1. You need to have configured the cf cli to point to your Cloud Foundry cluster, to be authenticated with your credentials and to be targeted at the organization and space where you want the console application be created. -1. You may need to configure Application Security Groups on your Cloud Foundry Cluster in order that Stratos can communicate with the Cloud Foundry API. See [below](#application-security-groups) for more information. -1. The Stratos Console will automatically detect the API endpoint for your Cloud Foundry. To do so, it relies on the `cf_api_url` value inside the `VCAP_APPLICATION` environment variable. If this is not provided by your Cloud Foundry platform, then you must manually update the application manifest as described [below](#console-fails-to-start). - -### Running Stratos in Production Environments - -Please be aware of the following when running Stratos in a production environment: - -#### Configure a Session Store Secret - -Stratos uses a Session Store Secret to protect the user session cookie. We recommend that you set your own value for this secret - choosing an alphanumeric string of your choice. - -You can configure this secret by editing the application manifest and adding to the `env` section, e.g. - -``` -applications: -- name: console - ... memory, disk settings here - env: - SESSION_STORE_SECRET: -``` - -#### Pre-configure UAA client used for user invites - -> You can skip this step and configure any CFs invite clients via the Stratos UI. - - To set the UAA client for user invites, supply the client id and client secret as environment variables as shown below: - - ``` - INVITE_USER_CLIENT_ID= - INVITE_USER_CLIENT_SECRET= - ``` - -This will set the the UAA client and UAA secret used to invite users for the default CF only. - -See the [invite users guide](../../docs/invite-user-guide.md) for more information about user invites in Stratos. - -#### Use of the Default Embedded SQLite Database - -We do not recommend deploying Stratos to a production environment using the default embedded SQLite Database. Instead we recommend creating -and binding a database service instance to Stratos - for more information see [here](db-migration/README.md). - -### Deploy Stratos from source - -To do so, `clone` the **stratos** repository, `cd` into the newly cloned repository and `push` to Cloud Foundry. This can be done with: - -``` -git clone https://github.com/cloudfoundry/stratos -cd stratos -git checkout tags/stable -b stable -./build/store-git-metadata.sh -cf push -``` - -If the cf push exceeds the time allowed see the instructions [here](#Pre-building-the-UI) - -#### Pre-building the UI - -Due to the memory usage of the Angular compiler (see below), when deployed to Cloud Foundry via `cf push`, Stratos does not use AOT (Ahead-of-Time) compilation. - -If you wish to enable AOT or reduce the push time, you can pre-build the UI before pushing. - -This can be done with: - -``` -git clone https://github.com/cloudfoundry/stratos -cd stratos -npm install -npm run prebuild-ui -cf push -``` - -You will need a recent version of Node installed locally to do this. - -The `prebuild-ui` npm script performs a build of the front-end UI and then zips up the resulting folder into a package named `stratos-frontend-prebuild.zip`. The Stratos buildpack will unpack this zip file and use its contents instead of building the UI during staging, when this file is present. - - -#### Memory Usage - -The Stratos Cloud Foundry `manifest.yml` states that the application requires -`1512MB` of memory. This is required during the build process of the -application since building an angular2 app is a memory intensive process. The -memory limit can be scaled down after the app has been pushed, using the cf CLI. - -### Deploy Stratos from docker image - -Deploy Stratos using the [`splatform/stratos`](https://hub.docker.com/r/splatform/stratos) docker image - -> **NOTE:** Your Cloud Foundry must have docker support [enabled](https://docs.cloudfoundry.org/adminguide/docker.html#enable). - -``` -cf push console -o splatform/stratos:stable -m 128M -k 384M -``` -> Note: You can replace `console` in the command above with a name of your choice for the application - -Alternatively cf push using a manifest - -- download [manifest-docker.yml](../../manifest-docker.yml) or create your own manifest file: - ```yaml - applications: - - name: console - docker: - image: splatform/stratos:stable - instances: 1 - memory: 128M - disk_quota: 384M - ``` -- now, you can simply push it to Cloud Foundry: - ``` - cf push -f manifest-docker.yml - ``` - -## Associate Cloud Foundry database service -Follow instructions [here](db-migration/README.md). - -## Use SSO Login - -By default Stratos will present its own login UI and only supports username and password authentication with your UAA. You can configure Stratos to use UAA's login UI by specifying the the `SSO_LOGIN` environment variable in the manifest, for example: - -``` -applications: -- name: console - ... memory, disk settings here - env: - SSO_LOGIN: true -``` - -When SSO Login is enabled, Stratos will also auto-connect to the Cloud Foundry it is deployed in using the token obtained during the SSO Login flow. - -For more information - see [Single-Sign On](../../docs/sso.md). - -## 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: - -``` -[ - { - "destination":"0.0.0.0-255.255.255.255", - "protocol":"all" - } -] -``` - -Save this to a file, e.g. `my-asg.json`. - -> Note: this allows example all network traffic on all IP ranges - we don't recommend using this. - -Unbind the existing ASG for you organization (`ORG`) and space (`SPACE`) with: - -``` -cf unbind-security-group public_networks ORG SPACE -``` - -Create a new ASG using the definition you saved to a file and give it a name, with: - -``` -cf create-security-group NAME my-asg.json -``` - -Bind this ASG to your `ORG` and `SPACE` with: - -``` -cf bind-security-group NAME ORG SPACE -``` - - -### Console fails to start - -The Stratos Console will automatically detect the API endpoint for your Cloud Foundry. To do so, it relies on the `cf_api` value inside the `VCAP_APPLICATION` environment variable. -To check if the variable is present, use the CF CLI to list environment variables, and inspect the `VCAP_APPLICATION` variable under `System-Provided`. - -``` -$ cf env console -Getting env variables for app console in org SUSE / space dev as admin... -OK - -System-Provided: - - - { - "VCAP_APPLICATION": { - "application_id": ..., - "application_name": "console", - "application_uris": ... - "application_version": ..., - "cf_api": "http://api.cf-dev.io", - ... - } - - No user-defined env variables have been set - ... -``` - -If the `cf_api` environment variable is absent then set the `CF_API_URL` variable. See the following _Setting the `CF_API_URL` env variable in the manifest_ section. - - -However, if the `cf_api` environment variable is present, and an HTTP address is specified, it is possible that insecure traffic may be blocked. See the following _Setting the `CF_API_FORCE_SECURE` env variable in the manifest_ section. - - -#### Setting the `CF_API_URL` env variable in the manifest - -To specify the Cloud Foundry API endpoint, add the `CF_API_URL` variable to the manifest, for example: - -``` -applications: -- name: console - memory: 256M - disk_quota: 256M - host: console - timeout: 180 - buildpack: https://github.com/cloudfoundry/stratos-buildpack - health-check-type: port - env: - CF_API_URL: https://<>> -``` - -#### Setting the `CF_API_FORCE_SECURE` env variable in the manifest - -To force the console to use secured communication with the Cloud Foundry API endpoint (HTTPS rather than HTTP), specify the `CF_API_FORCE_SECURE` environment in the manifest, for example: - -``` -applications: -- name: console - memory: 256M - disk_quota: 256M - host: console - timeout: 180 - buildpack: https://github.com/cloudfoundry/stratos-buildpack - health-check-type: port - env: - CF_API_FORCE_SECURE: true -``` - diff --git a/deploy/kubernetes/console/README.md b/deploy/kubernetes/console/README.md index cc4a7399d4..269a6c24b8 100644 --- a/deploy/kubernetes/console/README.md +++ b/deploy/kubernetes/console/README.md @@ -256,7 +256,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: @@ -407,4 +407,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/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 2aeca4f947..0000000000 --- a/docs/contributing.md +++ /dev/null @@ -1,85 +0,0 @@ -# Contributing to Stratos UI - -## Reporting issues - -Before reporting an issue, please check whether it has already been reported -[here](https://github.com/cloudfoundry/stratos/issues). If this is the case, please: - -- Read all the comments to confirm that it's the same issue you're having. -- Refrain from adding "same thing here" or "+1" comments. Just hit the - "subscribe" button to get notifications for this issue. -- Add a comment only if you can provide helpful information that has not been - provided in the discussion yet. - -If you want to report a **new issue**, please ensure you give as much detail -as possible about your setup/environment and provide sufficient steps -for the issue to be easily reproduced. - -## Check for assigned people - -We use Github Issues for submitting known issues (e.g. bugs, features, -etc.). Some issues will have someone assigned, meaning that there's already -someone that takes responsibility for fixing the issue. This is not done to -discourage contributions, rather to not step in the work that has already been -done by the assignee. If you want to work on a known issue with someone already -assigned to it, please contact the assignee first (e.g. by -mentioning the assignee in a new comment on the specific issue). This way you -can contribute with ideas, or even with code if the assignee decides that you -can step in. - -If you plan to work on a non assigned issue, please add a comment on the issue -to prevent duplicated work. - -## Sign your work - -The sign-off is a simple line at the end of the explanation for the patch. Your -signature certifies that you wrote the patch or otherwise have the right to pass -it on as an open-source patch. The rules are pretty simple: if you can certify -the below (from [developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -Then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -Use your real name (sorry, no pseudonyms or anonymous contributions.) - -If you set your `user.name` and `user.email` git configs, you can sign your -commit automatically with `git commit -s`. diff --git a/docs/developers-guide.md b/docs/developers-guide.md deleted file mode 100644 index 3ffc04e9e5..0000000000 --- a/docs/developers-guide.md +++ /dev/null @@ -1,294 +0,0 @@ - -# Developing the Stratos Console - -1. [Introduction](#introduction) -1. [Frontend Development](#frontend-development) -1. [Backend Development](#backend-development) - -## Introduction - -Stratos comprises of two main components: - -- A front-end UI that runs in your web browser. This is written in [Typescript](https://www.typescriptlang.org/) and uses the [Angular](https://angular.io/) framework. -- A back-end that provides a web-based API to the front-end. This is written in Go. - -Depending on what you are contributing, you will need to develop with the front-end, back-end or both. - -## Frontend Development - -### Introduction to the stack - -Have a look through the [Env + Tech](developers-guide-env-tech.md) page to get acquainted with some of the new technologies used in v2. -These include video's, tutorials and examples of Angular 2+, Typescript and Redux. There's also some advice on helpful plugins to use if -using Visual Studio Code. If you feel comfortable with these and are happy with your dev environment please skip straight to -[Set up Dependencies](#set-up-dependencies) - -### Set up Dependencies - -* Set up a Stratos backend - The frontend cannot run without a backend. Both backend and frontend exist in this same repo. - * Don't need to make changes to the backend code? To set up a backend run through the [deploy section](https://github.com/cloudfoundry/stratos/blob/master/deploy/README.md), - choose a deployment method and bring one up. These deployments will bring up the entire backend, including api service and database - along with a V2 frontend. - * Need to make changes to the backend code? Follow the below [Backend Development](#Backend-Development) set up guide -* Install [NodeJs](https://nodejs.org) (minimum node version 12.13.0) -* Install [Angular CLI](https://cli.angular.io/) - `npm install -g @angular/cli` - -### Configuration - -Configuration information can be found in two places - -* `./proxy.conf.js` - * In new forks this is missing and needs to be created using `./proxy.conf.template.js` as a template. - * Contains the address of the backend. Which will either be... - * If the backend is deployed via the instructions in the [deploy section](https://github.com/cloudfoundry/stratos/blob/master/deploy/README.md) - the url will be the same address as the V1 console's frontend address. For instance `https://localhost` would translate to - ``` - const PROXY_CONFIG = { - "/pp": { - "target": { - "host": "localhost", - "protocol": "https:", - "port": 443 - }, - "secure": false, - "changeOrigin": true, - "ws": true, - } - ``` - * If the backend is running locally using the instructions [Backend Development](#Backend-Development) below the url will local host - with a port of the `CONSOLE_PROXY_TLS_ADDRESS` value from `src/jetstream/config.properties`. By default this will be 5445. For - instance - ``` - const PROXY_CONFIG = { - "/pp": { - "target": { - "host": "localhost", - "protocol": "https:", - "port": 5443 - }, - "ws": true, - "secure": false, - "changeOrigin": true, - } - } - ``` -* `./src/frontend/environments/environment.ts` for developer vs production like config - * This contains more general settings for the frontend and does not usually need to be changed - -## Run the frontend - -1. (First time only) Copy `./proxy.conf.template.js` to `./proxy.conf.js` and update with required Jetstream url (see above for more info) -1. Run `npm install` -1. Run `npm start` for a dev server. (the app will automatically reload if you change any of the source files) - * If this times out please use `npm run start-high-mem` instead - * To change the port from the default 4200, add `-- --port [new port number]` - * To stop the automatic reload every time a resource changes add `-- --live-reload false` - * To do both the above use `-- --live-reload false --port [new port number]` -1. Navigate to `https://localhost:4200/`. The credentials to log in will be dependent on the Jetstream the console points at. Please refer - to the guides used when setting up the backend for more information - -## Build - -Run `npm run build` to build the project. - -The build artefacts will be stored in the `dist/` directory. This will output a production build of the application. - -## Creating angular items via angular cli - -To create a new angular component run `ng generate component component-name`. You can use a similar command to create other types of angular -items `ng generate `. - -## Theming - -We use the angular material theming mechanism. See [here](https://material.angular.io/guide/theming-your-components) for more information about theming new components added to stratos. - -## Test - -### Lint - -Run `npm run lint` to execute tslint lint checking. - -### Unit tests - -Run `npm test` to execute the unit tests via [Karma](https://karma-runner.github.io). Coverage information can be found in `./coverage` - -To execute an individual package run `ng test `. To execute the tests again automatically on code changes add `--watch=true` - -> **NOTE** npm test will search for chrome on your path. If this is not so please set an env var CHROME_BIN pointing to your executable -(chromium is fine too). - -### End-to-end tests - -Run `npm run e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). - -Run `npm run e2e-dev` to execute end-to-end tests against a locally running instance on `https://localhost:4200` - -More information on the E2E tests and pre-requisites for running them is available here - [E2E Tests](developers-guide-e2e-tests.md). - -### Code Climate - -We use [Code Climate](https://codeclimate.com/github/cloudfoundry-incubator/stratos) to check for general code quality issues. This executes against Pull -Requests on creation/push. - -#### Running Code Climate locally -> Generally we would not advise doing this and just rely on the code climate gate to run when pull requests are submitted - -To run locally see instructions [here](https://github.com/codeclimate/codeclimate) to install Code Climate CLI -and engine via docker. Once set ensure you're in the root of the project and execute the following (it may take a while) - -``` -codeclimate analyze -``` - -> **NOTE** Unfortunately this highlights all current issues and not those that are the diff between any master and feature branch. Analyze -can be ran against a single/sub set of files, again with all current issues, but a little more digestible. - -``` -codeclimate analyze -``` - -In a feature branch to compare files that have changed to master, for instance, use the following - -``` -git checkout feature-branch-A -codeclimate analyze $(git diff --name-only master) -``` - -You can also run the above command via npm - -``` -npm run climate -``` - -### Stratos Continue Integration -For each new pull request and any subsequent pushes to it the following actions are executed -- Code quality analysis via Code Climate - https://codeclimate.com/ -- Jenkins CI run, covering.. - - Frontend lint check - - Backend lint check - - Frontend unit tests - - Backend unit tests - - End to end tests -- Security anaylsis via Snyk - https://snyk.io/ - -## Backend Development - -Jetstream is the back-end for Stratos. It is written in Go. - -We use Go Modules for dependency management. - -### Pre-requisites - -You will need the following installed/available: - -* go 1.12 or later. - -*For authentication, **either*** - -* A UAA instance -* A local user account - -### Building the back-end - - -#### Build - -From the `src/jetstream` folder, build the Stratos back-end with: - -``` -npm run build-backend -``` - -The back-end executable is named `jetstream` and should be created within the `src/jetstream` folder. - -### Configuration - -Configuration can either be done via -- Environment Variable and/or Config File -- In the UI when you first use a front end with this backend - -In all cases the configuration is saved to the database on first run. Any subsequent changes require the db to be reset. For the default sqlite -db provider this can be done by deleting `src/jetstream/console-database.db` - -#### Configure by Environment Variables and/or Config File - -By default, the configuration in file `src/jetstream/config.properties` will be used. These can be changed by environment variables -or an overrides file. - -##### Environment variable - -If you wish to use a local user account, ensure you have set the following environment variables: - -- `AUTH_ENDPOINT_TYPE=local` -- `LOCAL_USER` - The username for the local user -- `LOCAL_USER_PASSWORD` - The password for the local user -- `LOCAL_USER_SCOPE=stratos.admin` - This gives the local user admin permissions. Currently other roles are not available. - -If you have a custom uaa, ensure you have set the following environment variables: - -- `UAA_ENDPOINT`- the URL of your UAA - - If you have an existing CF and want to use the same UAA use the `authorization_endpoint` value from `[cf url]/v2/info` - For example for PCF Dev, use: `UAA_ENDPOINT=https://login.local.pcfdev.io`. -- `CONSOLE_CLIENT` - the Client ID to use when authenticating against your UAA (defaults to: 'cf') -- `CONSOLE_CLIENT_SECRET` - the Client ID to use when authenticating against your UAA (defaults to empty) -- `CONSOLE_ADMIN_SCOPE` - an existing UAA scope that will be used to identify users as `Stratos Admins` - -> To use a pre-built Stratos UAA container execute `docker run --name=uaa --rm -p 8080:8080 -P splatform/stratos-uaa`. The UAA will be - available at `http://localhost:8080` with a `CONSOLE_CLIENT` value of `console` - -##### Config File - -To easily persist configuration settings copy `src/jetstream/config.example` to `src/jetstream/config.properties`. The backend will load its -configuration from this file in preference to the default config file, if it exists. You can also modify individual configuration settings -by setting the corresponding environment variable. - -##### To configure a local user account via config file - -In `src/jetstream/config.properties` uncomment the following lines: - -``` -AUTH_ENDPOINT_TYPE=local -LOCAL_USER=localuser -LOCAL_USER_PASSWORD=localuserpass -LOCAL_USER_SCOPE=stratos.admin -``` - -Load the Stratos UI and proceed to log in using the configured credentials. - -#### To configure UAA via Stratos - -1. Go through the `Config File` step above and comment out the `UAA_ENDPOINT` with a `#` in the new `config.properties` file. -1. If any previous configuration attempt has been made reset your database as described above. -1. Continue these steps from [Run](#run). - - You should see the line `Will add setup route and middleware` in the logs -1. Load the Stratos UI as usual and you should be immediately directed to the setup wizard - -The setup wizard that allows you to enter the values normally fetched from environment variables or files. The UI will assist you through -this process, validating that the UAA address and credentials are correct. It will also provide a list of possible scopes for the Stratos Admin - -#### Run - -Execute the following file from `src/jetstream` - -``` -jetstream -``` - -You should see the log as the backend starts up. You can press CTRL+C to stop the backend. - - -#### Automatically register and connect to an existing endpoint -To automatically register a Cloud Foundry add the environment variable/config setting below: - -``` -AUTO_REG_CF_URL= -``` - -Jetstream will then attempt to auto-connect to it with the credentials supplied when logging into Stratos. - -#### Running Jetstream in a container - -We recommend running Stratos using the Docker All-In-One image. - -* Follow instructions in the deploy/all-in-one docs - diff --git a/docs/i18n.md b/docs/i18n.md deleted file mode 100644 index 0fc6e721e9..0000000000 --- a/docs/i18n.md +++ /dev/null @@ -1,3 +0,0 @@ -# Internationalization (i18n) - -WIP diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index a6bdc1e312..0000000000 --- a/docs/index.html +++ /dev/null @@ -1 +0,0 @@ -

Hello GH Pages

diff --git a/docs/issue_template.md b/docs/issue_template.md index dffaf1add3..0cebba37fc 100644 --- a/docs/issue_template.md +++ b/docs/issue_template.md @@ -1,8 +1,9 @@ - + ### Stratos Version + ### Frontend Deployment type @@ -33,7 +34,7 @@ Insert your log here ``` - + ### Detailed Description diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index c1640d9390..0000000000 --- a/docs/overview.md +++ /dev/null @@ -1,64 +0,0 @@ -# Stratos Overview - -The Stratos Console provides a web-based UI to allow developers and administrators to manage their applications and cloud foundry deployment(s). - -It is designed to manage one or more Cloud Foundry deployments. It does so by managing "endpoints", where each endpoint is a reference to a Cloud Foundry deployment. The notion of an endpoint is not specific to Cloud Foundry, allowing Stratos to connect to other service types in the future. - -Stratos stores endpoint metadata in a relational database. Administrators of Stratos are able to register (add) new endpoints to the Console. All users are able to then connect to these endpoints using their credentials, ensuring that they get the appropriate level of access when interacting with Cloud Foundry. - -The high-level architecture of Stratos is shown in the diagram below: - -![Stratos High-Level Architecture](images/high-level-arch.png) - -The main components: - -* Web UI - Single-page AngularJS web application providing the front-end that runs in the user's browser. -* API Server - Provides the back-end APIs that support the front-end UI. This API takes care of authentication, endpoint management and proxying API requests from the front-end to the desired back-end API. -* Endpoint Datastore - Relational database that stores the registered endpoints and the encrypted user access tokens. - -## Authentication - -Stratos UI authenticates users using a Cloud Foundry UAA service. It must be configured with the details necessary to communicate with a UAA. When the user logs in to the Console, their login will be validated with the UAA. The Console uses a scope to identify Console administrators from regular users. - -Administrators use the 'Endpoints Dashboard' within the Console to add new endpoints to the Console. All users are then able to connect to these endpoints by providing their credentials. The Console will use these credentials to communicate with the UAA for the given endpoint (typically Cloud Foundry) and obtain a refresh and access token. These tokens are encrypted and stored in the Endpoint Datastore. - -When a user interacts with the Console and API requests need to be made to a given Cloud Foundry endpoint, these are sent to the API Server along with a custom http header which indicated which endpoint(s) the requests should be send to. The API Server will forward the request to the appropriate endpoints, first looking up the access and refresh tokens required to communicate with the endpoint(s). If any access token has expired, it will use the refresh token to obtain a new access token. - -## Deployment - -Stratos UI can be deployed in a number of environments: - -* Deployed in Cloud Foundry, as an application. See [guide](../deploy/cloud-foundry) -* Deployed in Kubernetes, using a Helm chart. See [guide](../deploy/kubernetes) -* Deployed in Docker, single container deploying all components. See [guide](../deploy/all-in-one) - -There are differences between the deployments as follows: - -### 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/README.md), 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/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index 25c55f2698..0000000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,39 +0,0 @@ -# Stratos Roadmap - Out of date - -Last Updated: 2 July 2018 - -# Version 2 Timeline - -The current focus is on releasing V2 of Stratos. The current timeline is: - -|Date|Milestone| -|---|---| -|15 June|Beta 1| -|20 June|Beta 2| -|25 June|RC 1| -|29 June|RC 2| -|20 July|2.0.0| - -Post 2.0 is released we will be working towards a regular recycle cycle each Sprint - we may start with Monthly releases and finally to releases each 2 weeks. - -## Agile - -We work on a 2-week Sprint cycle. Sprints start on Wednesdays. For reference, Sprint 27 started 4 April 2018. - -We are using GitHub issues to track all work items. See: https://github.com/cloudfoundry/stratos/issues - -## High-Level Features - -The high-level features that we schedule into the roadmap are identified by the ```feature-request``` label. You can see the current set of features [here](https://github.com/cloudfoundry/stratos/issues?q=is%3Aopen+is%3Aissue+label%3Afeature-request). - -### Near-term roadmap - -|#|Description|Issue|Notes| -|---|---|---|---| -|1|Technology Refresh (AngularJS => Angular)|[\#1972](https://github.com/cloudfoundry/stratos/issues/1972)|[Notes](planning/angular.md)| -|2|1st class support for service plan & service instance|[\#1391](https://github.com/cloudfoundry/stratos/issues/1391)|[Notes](planning/services.md)| -|3|Add support for Application and CF Metrics|[\#1985](https://github.com/cloudfoundry/stratos/issues/1985)|[Notes](planning/metrics.md)| -|4|Support UAA login UX directly (SSO)|[\#1384](https://github.com/cloudfoundry/stratos/issues/1384)|| -|5|Support per-endpoint Client ID and Client Secret|[\#2220](https://github.com/cloudfoundry/stratos/issues/2220)|| -|6|Bring Orgs and Spaces view to top-level|[\#2619](https://github.com/cloudfoundry/stratos/issues/2619)|| -|7|Deploy application: Enable deploying from private Git repositories|[\#1442](https://github.com/cloudfoundry/stratos/issues/1442)|| diff --git a/index.yaml b/index.yaml deleted file mode 100755 index 2d8ee50438..0000000000 --- a/index.yaml +++ /dev/null @@ -1,76 +0,0 @@ -apiVersion: v1 -entries: - console: - - apiVersion: v1 - created: 2018-01-09T11:48:55.233833731Z - description: A Helm chart for deploying Stratos UI Console - digest: 378df78adeebfad7d81b63a9f01afbb830c35cf948e3b662349e1d20a0972955 - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/1.0.0/console-helm-chart-1.0.0.tgz - version: 1.0.0 - - apiVersion: v1 - created: 2017-12-08T13:21:38.611521378Z - description: A Helm chart for deploying Stratos UI Console - digest: 8e8994171cf7ba37c4b37564c8efa07f1fd66dda347900b592ebfaae5407bf3d - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.9/console-helm-chart-0.9.9.tgz - version: 0.9.9 - - apiVersion: v1 - created: 2017-11-23T16:31:10.781104928Z - description: A Helm chart for deploying Stratos UI Console - digest: 97bdf40f53053815016e223d49082ba16984b9b5a0a5a2d237ef45bb42183ad8 - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.8/console-helm-chart-0.9.8.tgz - version: 0.9.8 - - apiVersion: v1 - created: 2017-11-09T11:58:41.085073375Z - description: A Helm chart for deploying Stratos UI Console - digest: 1a297cebb9bf8d34fe4d679203082fb89894d9b90583988fb0a1349a27dde920 - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.7/console-helm-chart-0.9.7.tgz - version: 0.9.7 - - apiVersion: v1 - created: 2017-11-01T11:57:35.330202636Z - description: A Helm chart for deploying Stratos UI Console - digest: 08611ec5de41a71567a033c4975752f31ca895b26316592a75d6dc93c2968e5f - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.6/console-helm-chart-0.9.6.tgz - version: 0.9.6 - - apiVersion: v1 - created: 2017-09-21T14:17:00.259268006+01:00 - description: A Helm chart for deploying Console - digest: c0aa7067eebd02cbf775f1adde1948ff679f3753f5d6bb7403798260ad8278d7 - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.5/console-helm-chart-0.9.5.tgz - version: 0.9.5 - - apiVersion: v1 - created: 2017-08-21T16:05:19.606723792Z - description: A Helm chart for deploying Console - digest: 488b5011edcc0b22a28f4e70e576351cc6b9f0f34198fb366cc53cddc197c9d1 - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.2/console-helm-chart-0.9.2.tgz - version: 0.9.2 - - apiVersion: v1 - created: 2017-08-01T10:54:22.706325757Z - description: A Helm chart for deploying Console - digest: 5c7c2769771d7648647ed33a9e7c326c95cf550cb165aa3144dc8f8062dc66bb - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.1/console-helm-chart-0.9.1.tgz - version: 0.9.1 - - apiVersion: v1 - created: 2017-07-27T13:08:56.409964314Z - description: A Helm chart for deploying Console - digest: e05d4dd12d3e518ce8d123480196008815988dc59fa3653ad4593042e92cc36b - name: console - urls: - - https://github.com/cloudfoundry-incubator/stratos/releases/download/0.9.0/console-helm-chart-0.9.0.tgz - version: 0.9.0 -generated: 2018-01-09T11:48:55.232685995Z diff --git a/website/.gitignore b/website/.gitignore new file mode 100644 index 0000000000..b37ff6e4c3 --- /dev/null +++ b/website/.gitignore @@ -0,0 +1,23 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +/website/build +/website/site-dist \ No newline at end of file diff --git a/website/README.md b/website/README.md new file mode 100644 index 0000000000..b70a5be1d0 --- /dev/null +++ b/website/README.md @@ -0,0 +1,40 @@ +# Stratos Website + +This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator. + +> Run the commands below in the `website` folder. + +### Installing Dependencies + +``` +$ npm install +``` + +### Local Development + +``` +$ npm start +``` + +This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server. + +> Note this command will open a web browser on the locally served site (http://localhost:3000) + +### Build + +``` +$ ./deploy.sh -b +``` + +This command generates static content into the `build` directory and can be served using any static contents hosting service. + +### Deployment + +We use GitHub pages - this command is a convenient way to build the website and push to the `gh-pages` branch. + +``` +$ ./deploy.sh +``` + + +> Note: The website is deployed to the GitHub Repository `cf-stratos/wesbite` which hosts https://stratos.app \ No newline at end of file diff --git a/website/babel.config.js b/website/babel.config.js new file mode 100644 index 0000000000..e00595dae7 --- /dev/null +++ b/website/babel.config.js @@ -0,0 +1,3 @@ +module.exports = { + presets: [require.resolve('@docusaurus/core/lib/babel/preset')], +}; diff --git a/website/deploy.sh b/website/deploy.sh new file mode 100755 index 0000000000..bdf2c28552 --- /dev/null +++ b/website/deploy.sh @@ -0,0 +1,101 @@ +#!/usr/bin/env bash + +# Build and deploy the website + +set -euo pipefail + +ARG=${1:-deploy} + +# wesbite folder +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )" + +pushd $DIR > /dev/null +echo "Building website ..." + +# 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 +tail -n +2 ${DIR}/../deploy/kubernetes/console/README.md >> ./docs/deploy/kubernetes/install.md + +# License file + +cat << EOF > ./docs/license.md +--- +id: license +title: License +sidebar_label: License +--- + +Stratos is licensed under the Apache 2.0 Software License, shown below: + +\`\`\` +EOF + +cat ${DIR}/../LICENSE >> ./docs/license.md +echo "\`\`\`" >> ./docs/license.md + +# Contributing + +cat << EOF > ./docs/developer/contributing.md +--- +title: Contributing +sidebar_label: Contributing +--- + +EOF + +tail -n +2 ${DIR}/../CONTRIBUTING.md >> ./docs/developer/contributing.md + +# Copy and generate files only +if [ "$ARG" == "-g" ]; then + exit 0 +fi + +npm run build + +# Generate and build only +if [ "$ARG" == "-b" ]; then + exit 0 +fi + +msg="Website update: $(date)" + +tmpdir=./site-dist +rm -rf site-dist +mkdir -p $tmpdir +pushd $tmpdir +echo "Cloning web site" +git clone git@github.com:cf-stratos/website.git + +echo "Copying newer site content ..." +rsync --delete --exclude=.git -r $DIR/build/ ./website + +cd website + +echo "Adding CNAME file" +echo "stratos.app" > CNAME + +if [ -z "$(git status --porcelain)" ]; then + echo "No changes to publish" +else + echo "Website has changed" + echo "Adding all files" + git add -A + git commit -m "${msg}" + echo "Pushing changes ..." + git push +fi + +popd > /dev/null + +echo "Removing website dist folder" +rm -rf $tmpdir + +popd > /dev/null diff --git a/docs/bosh-metrics.md b/website/docs/advanced/bosh-metrics.md similarity index 98% rename from docs/bosh-metrics.md rename to website/docs/advanced/bosh-metrics.md index f2bd8e5226..8b71e0d51a 100644 --- a/docs/bosh-metrics.md +++ b/website/docs/advanced/bosh-metrics.md @@ -1,4 +1,7 @@ -# Connecting Prometheus-boshrelease to Stratos +--- +title: Connecting Prometheus-boshrelease to Stratos +sidebar_label: Connecting Prometheus-boshrelease +--- Stratos can show some metrics stored in Prometheus. diff --git a/docs/invite-user-guide.md b/website/docs/advanced/invite-user-guide.md similarity index 92% rename from docs/invite-user-guide.md rename to website/docs/advanced/invite-user-guide.md index 58f9283f96..be3690db5d 100644 --- a/docs/invite-user-guide.md +++ b/website/docs/advanced/invite-user-guide.md @@ -1,4 +1,7 @@ -# Invite User Guide +--- +title: Configuring Invite User Support +sidebar_label: Configuring User Invites +--- Stratos provides a way for Cloud Foundry administrators and organization managers to invite users to an organization or space. @@ -39,14 +42,14 @@ In the above example the client id is `stratos-invite` and client secret is `pas Alternatively, you can use an existing UAA Client, if one is already available with the appropriate scopes. -> Note: You will need the Client ID and Client Secret used above when enabling User Invite support in the Stratos UI +> Note: You will need the Client ID and Client Secret used above when enabling User Invite support in Stratos ## Configuring SMTP Server details and (optionally) modifying Email Templates Configuration depends on how you have deployed Stratos. -1. For cf push, see [Configuration for CF Push](#Configuration-for-CF-Push) -1. For Kubernetes with Helm, see: [Configuration for Helm Installation](#Configuration-for-Helm-Installation) +1. For cf push, see [Configuration for CF Push](#configuration-for-cf-push) +1. For Kubernetes with Helm, see: [Configuration for Helm Installation](#configuration-for-helm-installation) ## Enabling User Invite support in Stratos @@ -56,7 +59,7 @@ This action must be performed by an Administrator in Stratos. 1) Use the `Configure` button in the `User Invitation Support` section. 1) Supply the uaa client id and secret and click `Configure` -> Note: If Stratos has been deployed via `cf push` and the steps under the `Pre-configure invite UAA client` header in the [CF deploy guide](../deploy/cloud-foundry/README.md) have been followed, you will not follow these steps for the default CF. +> Note: If Stratos has been deployed via `cf push` and the steps under the `Pre-configure invite UAA client` header in the [CF deploy guide](../deploy/cloud-foundry/cloud-foundry) have been followed, you will not follow these steps for the default CF. ## Configuration for CF Push @@ -142,7 +145,7 @@ When developing locally, we recommend using [mailcatcher](https://mailcatcher.me To install mailcatcher via docker, use the following command: `docker run -d -p 1080:80 -p 1025:25 --name mail tophfr/mailcatcher`. Once mailcatcher is installed, continue to follow the instructions below. -SMTP server details can be set via rhe usual environment variable approach or, when running locally, in the `jetstream/config.properties` file (see Backend Development - Configuration in [developers-guide](./developers-guide.md)). The config settings, with example values, are as follows: +SMTP server details can be set via rhe usual environment variable approach or, when running locally, in the `jetstream/config.properties` file (see Backend Development - Configuration in [developers-guide](../developer/introduction)). The config settings, with example values, are as follows: ``` SMTP_FROM_ADDRESS=Stratos diff --git a/docs/sso.md b/website/docs/advanced/sso.md similarity index 96% rename from docs/sso.md rename to website/docs/advanced/sso.md index 8f9f747c67..6dfb23a357 100644 --- a/docs/sso.md +++ b/website/docs/advanced/sso.md @@ -1,4 +1,7 @@ -# Single Sign On +--- +title: Configuring Single Sign On +sidebar_label: Configuring Single Sign On +--- By default, Stratos will authenticate against a UAA using username and password, for both logging into Stratos and when connecting Cloud Foundry endpoints. diff --git a/docs/access.md b/website/docs/deploy/access.md similarity index 97% rename from docs/access.md rename to website/docs/deploy/access.md index e55688dc5c..81ffe6a171 100644 --- a/docs/access.md +++ b/website/docs/deploy/access.md @@ -1,4 +1,8 @@ -# Accessing Stratos +--- +id: access +title: Accessing Stratos +sidebar_label: Accessing Stratos +--- Depending on the deployment mode, you may require access to an UAA. Stratos also has the option to configure a local user account which removes the need for a UAA in non-Cloud Foundry deployments. diff --git a/deploy/all-in-one/README.md b/website/docs/deploy/all-in-one.md similarity index 91% rename from deploy/all-in-one/README.md rename to website/docs/deploy/all-in-one.md index a9d392934e..a8a8024c80 100644 --- a/deploy/all-in-one/README.md +++ b/website/docs/deploy/all-in-one.md @@ -1,12 +1,26 @@ -# Deploying with the All-In-One Docker Container +--- +id: all-in-one +title: Deploying with the All-In-One Docker Container +sidebar_label: Docker All-in-One +--- 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 new file mode 100644 index 0000000000..c1b0f3ce71 --- /dev/null +++ b/website/docs/deploy/cloud-foundry/cf-troubleshooting.md @@ -0,0 +1,157 @@ +--- +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: + +``` +[ + { + "destination":"0.0.0.0-255.255.255.255", + "protocol":"all" + } +] +``` + +Save this to a file, e.g. `my-asg.json`. + +> Note: this allows example all network traffic on all IP ranges - we don't recommend using this. + +Unbind the existing ASG for you organization (`ORG`) and space (`SPACE`) with: + +``` +cf unbind-security-group public_networks ORG SPACE +``` + +Create a new ASG using the definition you saved to a file and give it a name, with: + +``` +cf create-security-group NAME my-asg.json +``` + +Bind this ASG to your `ORG` and `SPACE` with: + +``` +cf bind-security-group NAME ORG SPACE +``` + + +## Console fails to start + +The Stratos Console will automatically detect the API endpoint for your Cloud Foundry. To do so, it relies on the `cf_api` value inside the `VCAP_APPLICATION` environment variable. +To check if the variable is present, use the CF CLI to list environment variables, and inspect the `VCAP_APPLICATION` variable under `System-Provided`. + +``` +$ cf env console +Getting env variables for app console in org SUSE / space dev as admin... +OK + +System-Provided: + + + { + "VCAP_APPLICATION": { + "application_id": ..., + "application_name": "console", + "application_uris": ... + "application_version": ..., + "cf_api": "http://api.cf-dev.io", + ... + } + + No user-defined env variables have been set + ... +``` + +If the `cf_api` environment variable is absent then set the `CF_API_URL` variable. See the following _Setting the `CF_API_URL` env variable in the manifest_ section. + + +However, if the `cf_api` environment variable is present, and an HTTP address is specified, it is possible that insecure traffic may be blocked. See the following _Setting the `CF_API_FORCE_SECURE` env variable in the manifest_ section. + + +#### Setting the `CF_API_URL` env variable in the manifest + +To specify the Cloud Foundry API endpoint, add the `CF_API_URL` variable to the manifest, for example: + +``` +applications: +- name: console + memory: 256M + disk_quota: 256M + host: console + timeout: 180 + buildpack: https://github.com/cloudfoundry/stratos-buildpack + health-check-type: port + env: + CF_API_URL: https://<>> +``` + +#### Setting the `CF_API_FORCE_SECURE` env variable in the manifest + +To force the console to use secured communication with the Cloud Foundry API endpoint (HTTPS rather than HTTP), specify the `CF_API_FORCE_SECURE` environment in the manifest, for example: + +``` +applications: +- name: console + memory: 256M + disk_quota: 256M + host: console + timeout: 180 + buildpack: https://github.com/cloudfoundry/stratos-buildpack + health-check-type: port + env: + CF_API_FORCE_SECURE: true +``` diff --git a/website/docs/deploy/cloud-foundry/cloud-foundry.md b/website/docs/deploy/cloud-foundry/cloud-foundry.md new file mode 100644 index 0000000000..1f876ced45 --- /dev/null +++ b/website/docs/deploy/cloud-foundry/cloud-foundry.md @@ -0,0 +1,162 @@ +--- +id: cloud-foundry +title: Deploying as a Cloud Foundry Application +sidebar_label: Deploy on Cloud Foundry +--- + +## Deployment Steps + +Stratos can be pushed as an application to Cloud Foundry. + +You can do it in two ways: + +1. [Deploy Stratos from source](#deploy-stratos-from-source) +1. [Deploy Stratos from docker image](#deploy-stratos-from-docker-image) + +You will then be able to open a web browser and navigate to the console URL: + +`https://console.` + +Where `` is the default domain configured for your Cloud Foundry cluster. + +To login use the following credentials detailed [here](../access). + +If you run into issues, please refer to the [Troubleshooting Guide](cf-troubleshooting) below. + +> The console will pre-configure the host Cloud Foundry endpoint. No other CF instance should be registered unless the instructions in + the section [Associate Cloud Foundry database service](#associate-cloud-foundry-database-service) are followed. + All other deployment methods (helm, docker all-in-one, etc) allow the registration of multiple CF instances by default. + +Note: + +1. You need the cf CLI command line tool installed and available on the path. +1. You need to have configured the cf cli to point to your Cloud Foundry cluster, to be authenticated with your credentials and to be targeted at the organization and space where you want the console application be created. +1. You may need to configure Application Security Groups on your Cloud Foundry Cluster in order that Stratos can communicate with the Cloud Foundry API. See [below](#application-security-groups) for more information. +1. The Stratos Console will automatically detect the API endpoint for your Cloud Foundry. To do so, it relies on the `cf_api_url` value inside the `VCAP_APPLICATION` environment variable. If this is not provided by your Cloud Foundry platform, then you must manually update the application manifest as described [below](#console-fails-to-start). + +### Running Stratos in Production Environments + +Please be aware of the following when running Stratos in a production environment: + +#### Configure a Session Store Secret + +Stratos uses a Session Store Secret to protect the user session cookie. We recommend that you set your own value for this secret - choosing an alphanumeric string of your choice. + +You can configure this secret by editing the application manifest and adding to the `env` section, e.g. + +``` +applications: +- name: console + ... memory, disk settings here + env: + SESSION_STORE_SECRET: +``` + +#### Pre-configure UAA client used for user invites + +> You can skip this step and configure any CFs invite clients via the Stratos UI. + + To set the UAA client for user invites, supply the client id and client secret as environment variables as shown below: + + ``` + INVITE_USER_CLIENT_ID= + INVITE_USER_CLIENT_SECRET= + ``` + +This will set the the UAA client and UAA secret used to invite users for the default CF only. + +See the [invite users guide](../guides/admin/invite-user-guide) for more information about user invites in Stratos. + +#### Use of the Default Embedded SQLite Database + +We do not recommend deploying Stratos to a production environment using the default embedded SQLite Database. Instead we recommend creating +and binding a database service instance to Stratos - for more information see [here](db-migration). + +### Deploy Stratos from source + +To do so, `clone` the **stratos** repository, `cd` into the newly cloned repository and `push` to Cloud Foundry. This can be done with: + +``` +git clone https://github.com/cloudfoundry/stratos +cd stratos +git checkout tags/stable -b stable +./build/store-git-metadata.sh +cf push +``` + +If the cf push exceeds the time allowed see the instructions [here](#pre-building-the-ui) + +#### Pre-building the UI + +Due to the memory usage of the Angular compiler (see below), when deployed to Cloud Foundry via `cf push`, Stratos does not use AOT (Ahead-of-Time) compilation. + +If you wish to enable AOT or reduce the push time, you can pre-build the UI before pushing. + +This can be done with: + +``` +git clone https://github.com/cloudfoundry/stratos +cd stratos +npm install +npm run prebuild-ui +cf push +``` + +You will need a recent version of Node installed locally to do this. + +The `prebuild-ui` npm script performs a build of the front-end UI and then zips up the resulting folder into a package named `stratos-frontend-prebuild.zip`. The Stratos buildpack will unpack this zip file and use its contents instead of building the UI during staging, when this file is present. + + +#### Memory Usage + +The Stratos Cloud Foundry `manifest.yml` states that the application requires +`1512MB` of memory. This is required during the build process of the +application since building an angular2 app is a memory intensive process. The +memory limit can be scaled down after the app has been pushed, using the cf CLI. + +### Deploy Stratos from docker image + +Deploy Stratos using the [`splatform/stratos`](https://hub.docker.com/r/splatform/stratos) docker image + +> **NOTE:** Your Cloud Foundry must have docker support [enabled](https://docs.cloudfoundry.org/adminguide/docker.html#enable). + +``` +cf push console -o splatform/stratos:stable -m 128M -k 384M +``` +> Note: You can replace `console` in the command above with a name of your choice for the application + +Alternatively cf push using a manifest + +- download [manifest-docker.yml](../../../manifest-docker.yml) or create your own manifest file: + ```yaml + applications: + - name: console + docker: + image: splatform/stratos:stable + instances: 1 + memory: 128M + disk_quota: 384M + ``` +- now, you can simply push it to Cloud Foundry: + ``` + cf push -f manifest-docker.yml + ``` + +## Associate Cloud Foundry database service +Follow instructions [here](db-migration). + +## Use SSO Login + +By default Stratos will present its own login UI and only supports username and password authentication with your UAA. You can configure Stratos to use UAA's login UI by specifying the the `SSO_LOGIN` environment variable in the manifest, for example: + +``` +applications: +- name: console + ... memory, disk settings here + env: + SSO_LOGIN: true +``` + +When SSO Login is enabled, Stratos will also auto-connect to the Cloud Foundry it is deployed in using the token obtained during the SSO Login flow. + +For more information - see [Single-Sign On](../../advanced/sso). diff --git a/deploy/cloud-foundry/db-migration/README.md b/website/docs/deploy/cloud-foundry/db-migration.md similarity index 90% rename from deploy/cloud-foundry/db-migration/README.md rename to website/docs/deploy/cloud-foundry/db-migration.md index 281b5f9352..98cd856928 100644 --- a/deploy/cloud-foundry/db-migration/README.md +++ b/website/docs/deploy/cloud-foundry/db-migration.md @@ -1,6 +1,10 @@ -# Associate a Cloud Foundry database service +--- +id: db-migration +title: Associate a Cloud Foundry database service +sidebar_label: Database service bindings +--- -As described in the standard `cf push` instructions [here](../README.md) Stratos, when deployed via `cf push`, +As described in the standard `cf push` instructions [here](cloud-foundry) Stratos, when deployed via `cf push`, does not contain any way to persist data over application restarts and db entries such as registered endpoints and user tokens are lost. To resolve this a Cloud Foundry db service can be bound to to it. Run through the steps below to implement. diff --git a/deploy/kubernetes/README.md b/website/docs/deploy/kubernetes.md similarity index 80% rename from deploy/kubernetes/README.md rename to website/docs/deploy/kubernetes.md index 6d8d583560..55ed9cfeb2 100644 --- a/deploy/kubernetes/README.md +++ b/website/docs/deploy/kubernetes.md @@ -1,4 +1,8 @@ -# Deploying in Kubernetes +--- +id: kubernetes +title: Deploying in Kubernetes +sidebar_label: Overview +--- Stratos can be deployed to Kubernetes using [Helm](https://github.com/kubernetes/helm). @@ -12,4 +16,4 @@ You will need to have both the `kubectl` and `helm` CLIs installed and available The Stratos Helm chart contains a `README.md` file that contains installation instructions and configuration documentation. -This document is also available in our GitHub repository here: [README.md](https://github.com/cloudfoundry/stratos/blob/master/deploy/kubernetes/console/README.md). +This document is also available in [here](kubernetes/helm-installation). diff --git a/website/docs/deploy/kubernetes/install.md b/website/docs/deploy/kubernetes/install.md new file mode 100644 index 0000000000..fad7b188d4 --- /dev/null +++ b/website/docs/deploy/kubernetes/install.md @@ -0,0 +1,413 @@ +--- +id: helm-installation +title: Deploying Using Helm +sidebar_label: Deploy using Helm +--- + +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. + +## Installation + +Stratos can be installed to a Kubernetes cluster using Helm. Either Helm 2 or Helm 3 can be used, although we recommend using the newer Helm 3 version. + +Ensure the [Helm](https://github.com/helm/helm) client and [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) CLIs are installed. If you are using Helm 2, ensure you've initialized Tiller into your cluster with the appropriate +Service Account. + +The Helm chart is published to the Stratos Helm repository. + +You will need to have the Stratos Helm repository added to your Helm setup, if you do not, run: + +``` +helm repo add stratos https://cloudfoundry.github.io/stratos +``` + +Check the repository was successfully added by searching for the `console`, for example: + +``` +helm search repo console +NAME CHART VERSION APP VERSION DESCRIPTION +stratos/console 3.2.0 3.2.0 A Helm chart for deploying Stratos UI Console +``` + +> Note: Version numbers will depend on the version of Stratos available from the Helm repository + +> Note: Commands shown in this document are for Helm version 3. For Helm version 2, when installing, instead of supplying the name via the `--name` flag, it is supplied as the first argument, before the chart name. + +To install Stratos: + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console +``` + +> **Note**: The first `kubectl` command will create a namespace for Stratos. With Helm 3 you must create a namespace before installing. +We recommend installing Stratos into a separate namespace. + +> **Note**: This assumes that a storage class exists in the Kubernetes cluster that has been marked as `default`. If no such storage class exists, a specific storage class needs to be specified, please see the following section *Specifying a custom Storage Class*. + +> You can change the namespace (--namespace) and the release name to values of your choice. + +This will create a Stratos instance named `my-console` in a namespace called `console` in your Kubernetes cluster. + +After the install, you should be able to access the Console in a web browser by following [the instructions](#accessing-the-console) below. + +Advanced installation topics are covered in the the [Advanced Topics](#advanced-topics) section below. + +# Helm Chart Configuration + +The following table lists the configurable parameters of the Stratos Helm chart and their default values. + +|Parameter|Description|Default| +|---|---|---| +|imagePullPolicy|Image pull policy|IfNotPresent| +|console.sessionStoreSecret|Secret to use when encrypting session tokens|auto-generated random value| +|console.ssoLogin|Whether to enable SSO Login and use the UAA Login UI instead of the built-in one|false| +|console.backendLogLevel|Log level for backend (info, debug)|info| +|console.service.externalIPs|External IPs to add to the console service|[]| +|console.service.loadBalancerIP|IP address to assign to the load balancer for the metrics service (if supported)|| +|console.service.loadBalancerSourceRanges|List of IP CIDRs allowed access to load balancer (if supported)|[]| +|console.service.type|Service type for the console (ClusterIP, NodePort, LoadBalancer, ExternalName etc)|ClusterIP| +|console.service.servicePort|Service port for the console service|443| +|console.service.externalName|External name for the console service when service type is ExternalName|| +|console.service.nodePort|Node port to use for the console service when service type is NodePort or LoadBalancer|| +|console.ingress.enabled|Enable ingress for the console service|false| +|console.ingress.host|Host for the ingress resource||| +|console.ingress.secretName|Name of an existing secret containing the TLS certificate for ingress||| +|console.service.http.enabled|Enabled HTTP access to the console service (as well as HTTPS)|false| +|console.service.http.servicePort|Service port for HTTP access to the console service when enabled|80| +|console.service.http.nodePort|Node port for HTTP access to the console service (as well as HTTPS)|| +|console.templatesConfigMapName|Name of config map that provides the template files for user invitation emails|| +|console.userInviteSubject|Email subject of the user invitation message|| +|console.techPreview|Enable/disable Tech Preview features|false| +|console.ui.listMaxSize|Override the default maximum number of entities that a configured list can fetch. When a list meets this amount additional pages are not fetched|| +|console.ui.listAllowLoadMaxed|If the maximum list size is met give the user the option to fetch all results|false| +|console.localAdminPassword|Use local admin user instead of UAA - set to a password to enable|| +|console.tlsSecretName|Secret containing TLS certificate to use for the Console|| +|console.mariadb.external|Use an external database instead of the built-in MariaDB|false| +|console.mariadb.database|Name of the database to use|console| +|console.mariadb.user|Name of the user for accessing the database|console| +|console.mariadb.userPassword|Password of the user for accessing the database. Leave blank for the built-in database to generate a random password|| +|console.mariadb.rootPassword|Password of the root user for accessing the database. Leave blank for the built-in database to generate a random password|| +|console.mariadb.host|Hostname of the database when using an external db|| +|console.mariadb.port|Port of the database when using an external db|3306| +|console.mariadb.tls|TLS mode when connecting to database (true, false, skip-verify, preferred)|false| +|uaa.endpoint|URL of the UAA endpoint to authenticate with || +|uaa.consoleClient|Client to use when authenticating with the UAA|cf| +|uaa.consoleClientSecret|Client secret to use when authenticating with the UAA|| +|uaa.consoleAdminIdentifier|Scope that identifies an admin user of Stratos (e.g. cloud_controller.admin|| +|uaa.skipSSLValidation|Skip SSL validation when when authenticating with the UAA|false| +|env.SMTP_AUTH|Authenticate against the SMTP server using AUTH command when Sending User Invite emails|false| +|env.SMTP_FROM_ADDRESS|From email address to use when Sending User Invite emails|| +|env.SMTP_USER|User name to use for authentication when Sending User Invite emails|| +|env.SMTP_PASSWORD|Password to use for authentication when Sending User Invite emails|| +|env.SMTP_HOST|Server host address to use for authentication when Sending User Invite emails|| +|env.SMTP_PORT|Server port to use for authentication when Sending User Invite emails|| +|kube.auth|Set to "rbac" if the Kubernetes cluster supports Role-based access control|"rbac"| +|kube.organization|Registry organization to use when pulling images|| +|kube.registry.hostname|Hostname of registry to use when pulling images|docker.io| +|kube.registry.username|Username to use when pulling images from the registry|| +|kube.registry.password|Password to use when pulling images from the registry|| +|console.podAnnotations|Annotations to be added to all pod resources|| +|console.podExtraLabels|Additional labels to be added to all pod resources|| +|console.statefulSetAnnotations|Annotations to be added to all statefulset resources|| +|console.statefulSetExtraLabels|Additional labels to be added to all statefulset resources|| +|console.deploymentAnnotations|Annotations to be added to all deployment resources|| +|console.deploymentExtraLabels|Additional labels to be added to all deployment resources|| +|console.jobAnnotations|Annotations to be added to all job resources|| +|console.jobExtraLabels|Additional labels to be added to all job resources|| +|console.service.annotations|Annotations to be added to all service resources|| +|console.service.extraLabels|Additional labels to be added to all service resources|| +|console.service.ingress.annotations|Annotations to be added to the ingress resource|| +|console.service.ingress.extraLabels|Additional labels to be added to the ingress resource|| +|console.nodeSelector|Node selectors to use for the console Pod|| +|mariadb.nodeSelector|Node selectors to use for the database Pod|| +|configInit.nodeSelector|Node selectors to use for the configuration Pod|| + +## Accessing the Console + +To check the status of the instance use the following command: + +``` +helm status my-console +``` + +> Note: Replace `my-console` with the value you used for the `name` parameter, or if you did not provide one, use the `helm list` command to find the release name that was automatically generated for you. + +The console is exposed via an HTTPS service - `RELEASE-NAME-ui-ext` (where RELEASE-NAME is the name used for the `name` parameter when installing). You can find the details of this service with: + +``` +kubectl get services -n NAMESPACE +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +my-console-mariadb ClusterIP 10.105.216.25 3306/TCP 60s +my-console-ui-ext NodePort 10.109.207.70 443:31067/TCP 60s +``` + +> In this example, Stratos has been deployed withe the service configured as `NodePort`. + +The URL you use for accessing Stratos will depend on the service configuration and the environment that you have used. + +> Note: If you did not provide a certificate when installing, Stratos will use a self-signed certificate, so you will see a certificate warning which you access Stratos in a browser. + +# Upgrading your deployment + +To upgrade your instance when using the Helm repository, fetch any updates to the repository: + +``` +helm repo update +``` + +To update an instance, the following assumes your instance is called `my-console`: + +``` +helm upgrade my-console stratos/console +``` + +After the upgrade, perform a `helm list` to ensure your console is the latest version. + +## Uninstalling + +To uninstall Stratos, delete the Helm release and also delete the Kubernetes namespace: + +``` +helm delete my-console --purge +kubectl delete namespace console +``` + +> Note: Stratos creates secrets in the namespace as part of an initialization job. These are not managed by Helm, so make sure you +delete the namespace to remove these secrets. + +# Advanced Topics + +## Using a Load Balancer + +If your Kubernetes deployment supports automatic configuration of a load balancer (e.g. Google Container Engine), specify the parameters `console.service.type=LoadBalancer` when installing. + + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console --set console.service.type=LoadBalancer +``` + +## Using an Ingress Controller + +If your Kubernetes Cluster supports Ingress, you can expose Stratos through Ingress by supplying the appropriate ingress configuration when installing. + +This configuration is described below: + +|Parameter|Description|Default| +|----|---|---| +|console.service.ingress.enabled|Enables ingress|false| +|console.service.ingress.annotations|Annotations to be added to the ingress resource.|{}| +|console.service.ingress.extraLabels|Additional labels to be added to the ingress resource.|{}| +|console.service.ingress.host|The host name that will be used for the Stratos service.|| +|console.service.ingress.secretName|The existing TLS secret that contains the certificate for ingress.|| + +You must provide `console.service.ingress.host` when enabling ingress. + +By default a certificate will be generated for TLS. You can provide your own certificate by creating a secret and specifying this with `console.service.ingress.secretName`. + +> Note: If you do not supply `console.service.ingress.host` but do supply `env.DOMAIN` then the host `console.[env.DOMAIN]` will be used. + +## Deploying from a Private Image Repository + +If the images used by the chart are hosted in a private repository, the following needs to be specified. Save the following to a file called `private_overrides.yaml`. Replace `REGISTRY USER PASSSWORD`, `REGISTRY USERNAME`, `REGISTRY URL` with the appropriate values. `USER EMAIL` can be left blank. + +``` +kube: + registry: + password: + username: + hostname: + email: +``` + +Deploy with: + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console -f private_overrides.yaml +``` + +## Deploying with your own TLS certificates + +By default the console will generate self-signed certificates for demo purposes. To configure Stratos to use your provided TLS certificate, create a TLS secret in the namespace you are installing into and specify this secret name using the helm chart value `console.tlsSecretName` when installing. + +Assuming you have your certificate and key in the files `tls.crt` and `tls.key`, create the secret with: + +``` +kubectl create secret tls -n NAMESPACE stratos-tls-secret --cert=tls.crt --key=tls.key +``` + +> Where `NAMESPACE` is the namespace you are installing Stratos into - you will need to manually create the namespace first if it does not already exist. + +You can now install Stratos with: + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console --set console.tlsSecretName=stratos-tls-secret + +``` + +## Using an External Database + +You can choose to use Stratos with an external database, rather than deploying a single-node MariaDB instance as part of the Helm install. + +To do so, specify `console.mariabdb.external=true` when deploying. + +You will also need to specify: + +- `console.mariadb.host` as the hostname of the external MariaDB database server +- `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.userPassword` as the password to connect to the database server + +When using an external database server, Stratos expects that you have: + +- Created a user that will be used to access the database +- Created a database for the Stratos tables and data +- Granted appropriate permissions so that the user can access the database + +> Note: When using a database from a Cloud provider, ensure that the username is correct - in some cases this will be `username@servername` - check the provided connection documentation + +## Specifying UAA configuration + +When deploying with SCF, the `scf-config-values.yaml` (see [SCF Wiki link](https://github.com/SUSE/scf/wiki/How-to-Install-SCF#configuring-the-deployment)) can be supplied when installing Stratos. + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console -f scf-config-values.yaml +``` + +UAA configuration can be specified by providing the following configuration. + +Create a yaml file with the content below and and update according to your environment and save to a file called `uaa-config.yaml`. +``` +uaa: + endpoint: https://uaa.cf-dev.io:2793 + consoleClient: cf + consoleClientSecret: + consoleAdminIdentifier: cloud_controller.admin + skipSSLValidation: false +``` + +To install Stratos with the above specified configuration: + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console -f uaa-config.yaml +``` + +## Configuring a local user account + +This allows for deployment without a UAA. To enable the local user account, supply a password for the local user in the deployment command, as follows. All other steps for each deployment method should be followed as in the preceding sections above. + +To deploy using our Helm repository: + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console --set console.localAdminPassword= +``` + +## Specifying Annotations and Labels + +In some scenarios it is useful to be able to add custom annotations and/or labels to the Kubernetes resources that the Stratos Helm chart creates. + +The Stratos Helm chart exposes a number of Helm chart values that cabe specified in order to do this - they are: + +|Parameter|Description|Default| +|----|---|---| +|console.podAnnotations|Annotations to be added to all pod resources|| +|console.podExtraLabels|Additional labels to be added to all pod resources|| +|console.statefulSetAnnotations|Annotations to be added to all statefulset resources| +|console.statefulSetExtraLabels|Additional labels to be added to all statefulset resources|| +|console.deploymentAnnotations|Annotations to be added to all deployment resources|| +|console.deploymentExtraLabels|Additional labels to be added to all deployment resources|| +|console.jobAnnotations|Annotations to be added to all job resources|| +|console.jobExtraLabels|Additional labels to be added to all job resources|| +|console.service.annotations|Annotations to be added to all service resources|| +|console.service.extraLabels|Additional labels to be added to all service resources|| +|console.service.ingress.annotations|Annotations to be added to the ingress resource|| +|console.service.ingress.extraLabels|Additional labels to be added to the ingress resource|| + +## Requirements + +### Storage Class + +Stratos uses persistent volumes. In order to deploy it in your Kubernetes environment, you must +have a storage class available. + +Without configuration, the Stratos Helm Chart will use the default storage class. If a default storage +class is not available, installation will fail. + +To check if a `default` storage class exists, you can list your configured storage classes with `kubectl get storageclass`. If no storage class has `(default)` after it, then you need to either specify a storage class override or declare a default storage class for your Kubernetes cluster. + +For non-production environments, you may want to use the `hostpath` storage class. See the [SCF instructions](https://github.com/SUSE/scf/wiki/How-to-Install-SCF#choosing-a-storage-class) for details on setting this up. Note that you will need to make this storage class the default storage class, e.g. + +``` +kubectl patch storageclass -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' +``` + +Where `` would be `hostpath` if you follow the SCF instructions. + + +### Specifying a custom Storage Class + +If no default storage class has been defined in the Kubernetes cluster. The Stratos helm chart will fail to deploy successfully. To check if a `default` storage class exists, you can list your configured storage classes with `kubectl`. If no storage class has `(default)` after it, then you need to either specify a storage class override or declare a default storage class for your Kubernetes cluster. + +#### Providing Storage Class override +``` +kubectl get storageclass +NAME TYPE +ssd kubernetes.io/host-path +persistent kubernetes.io/host-path +``` + +For instance to use the storage class `persistent` to deploy Console persistent volume claims, store the following to a file called `override.yaml`. + +``` +--- +storageClass: persistent +``` + +If you want MariaDB to use a specific storage class (which can be different to that used for the other components), then specify the following: +``` +--- +storageClass: persistent +mariadb: + persistence: + storageClass: persistent +``` + +Run Helm with the override: + +``` +kubectl create namespace console +helm install my-console stratos/console --namespace=console -f override.yaml +``` + +#### Create a default Storage Class + +Alternatively, you can configure a storage class with `storageclass.kubernetes.io/is-default-class` set to `true`. For instance the following storage class will be declared as the default. If you don't have the `hostpath` provisioner available in your local cluster, please follow the instructions on [link](https://github.com/kubernetes-incubator/external-storage/tree/master/docs/demo/hostpath-provisioner), to deploy one. + +If the hostpath provisioner is available, save the file to `storageclass.yaml` + +``` +--- +kind: StorageClass +apiVersion: storage.k8s.io/v1beta1 +metadata: + name: default + annotations: + storageclass.kubernetes.io/is-default-class: "true" +provisioner: kubernetes.io/host-path # Or whatever the local hostpath provisioner is called +``` + +To create it in your kubernetes cluster, execute the following. + +``` +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 new file mode 100644 index 0000000000..f3bf6e39d8 --- /dev/null +++ b/website/docs/deploy/overview.md @@ -0,0 +1,44 @@ +--- +id: overview +title: Deploying Stratos +sidebar_label: Overview +--- + +Stratos can be deployed in the following environments: + +1. Cloud Foundry, as an application. See [guide](cloud-foundry/cloud-foundry) +2. Kubernetes, using a Helm chart. See [guide](kubernetes) +3. Docker, single container deploying all components. See [guide](all-in-one) + +> 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. + +## 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](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/docs/troubleshooting.md b/website/docs/deploy/troubleshooting.md similarity index 78% rename from docs/troubleshooting.md rename to website/docs/deploy/troubleshooting.md index 138d8f7aec..c40f7065da 100644 --- a/docs/troubleshooting.md +++ b/website/docs/deploy/troubleshooting.md @@ -1,7 +1,11 @@ -# Troubleshooting +--- +id: troubleshooting +title: General Troubleshooting +sidebar_label: Troubleshooting +--- ## Deploying as a Cloud Foundry Application -See the custom troubleshooting guide [here](../deploy/cloud-foundry#troubleshooting). +See the custom troubleshooting guide [here](cloud-foundry/cf-troubleshooting). ## Usernames appear as long random characters when connected to IBM Cloud diff --git a/website/docs/developer/backend.md b/website/docs/developer/backend.md new file mode 100644 index 0000000000..f54dac53c0 --- /dev/null +++ b/website/docs/developer/backend.md @@ -0,0 +1,124 @@ +--- +title: Backend Development +sidebar_label: Overview +--- + +Jetstream is the back-end for Stratos. It is written in Go. + +We use Go Modules for dependency management. + +### Pre-requisites + +You will need the following installed/available: + +* go 1.12 or later. + +*For authentication, **either*** + +* A UAA instance +* A local user account + +### Building the back-end + + +#### Build + +From the `src/jetstream` folder, build the Stratos back-end with: + +``` +npm run build-backend +``` + +The back-end executable is named `jetstream` and should be created within the `src/jetstream` folder. + +### Configuration + +Configuration can either be done via +- Environment Variable and/or Config File +- In the UI when you first use a front end with this backend + +In all cases the configuration is saved to the database on first run. Any subsequent changes require the db to be reset. For the default sqlite +db provider this can be done by deleting `src/jetstream/console-database.db` + +#### Configure by Environment Variables and/or Config File + +By default, the configuration in file `src/jetstream/default.config.properties` will be used. These can be changed by environment variables +or an overrides file. + +##### Environment variable + +If you wish to use a local user account, ensure you have set the following environment variables: + +- `AUTH_ENDPOINT_TYPE=local` +- `LOCAL_USER` - The username for the local user +- `LOCAL_USER_PASSWORD` - The password for the local user +- `LOCAL_USER_SCOPE=stratos.admin` - This gives the local user admin permissions. Currently other roles are not available. + +If you have a custom uaa, ensure you have set the following environment variables: + +- `UAA_ENDPOINT`- the URL of your UAA + - If you have an existing CF and want to use the same UAA use the `authorization_endpoint` value from `[cf url]/v2/info` + For example for PCF Dev, use: `UAA_ENDPOINT=https://login.local.pcfdev.io`. +- `CONSOLE_CLIENT` - the Client ID to use when authenticating against your UAA (defaults to: 'cf') +- `CONSOLE_CLIENT_SECRET` - the Client ID to use when authenticating against your UAA (defaults to empty) +- `CONSOLE_ADMIN_SCOPE` - an existing UAA scope that will be used to identify users as `Stratos Admins` + +> To use a pre-built Stratos UAA container execute `docker run --name=uaa --rm -p 8080:8080 -P splatform/stratos-uaa`. The UAA will be + available at `http://localhost:8080` with a `CONSOLE_CLIENT` value of `console` + +##### Config File + +To easily persist configuration settings copy `src/jetstream/default.config.properties` to `src/jetstream/config.properties`. The backend will load its +configuration from this file in preference to the default config file, if it exists. You can also modify individual configuration settings +by setting the corresponding environment variable. + +##### To configure a local user account via config file + +In `src/jetstream/config.properties` uncomment the following lines: + +``` +AUTH_ENDPOINT_TYPE=local +LOCAL_USER=localuser +LOCAL_USER_PASSWORD=localuserpass +LOCAL_USER_SCOPE=stratos.admin +``` + +Load the Stratos UI and proceed to log in using the configured credentials. + +#### To configure UAA via Stratos + +1. Go through the `Config File` step above and comment out the `UAA_ENDPOINT` with a `#` in the new `config.properties` file. +1. If any previous configuration attempt has been made reset your database as described above. +1. Continue these steps from [Run](#run). + - You should see the line `Will add setup route and middleware` in the logs +1. Load the Stratos UI as usual and you should be immediately directed to the setup wizard + +The setup wizard that allows you to enter the values normally fetched from environment variables or files. The UI will assist you through +this process, validating that the UAA address and credentials are correct. It will also provide a list of possible scopes for the Stratos Admin + +#### Run + +Execute the following file from `src/jetstream` + +``` +jetstream +``` + +You should see the log as the backend starts up. You can press CTRL+C to stop the backend. + + +#### Automatically register and connect to an existing endpoint +To automatically register a Cloud Foundry add the environment variable/config setting below: + +``` +AUTO_REG_CF_URL= +``` + +Jetstream will then attempt to auto-connect to it with the credentials supplied when logging into Stratos. + +#### Running Jetstream in a container + +We recommend running Stratos using the Docker All-In-One image. + +* Follow instructions in the deploy/all-in-one docs + diff --git a/website/docs/developer/contributing.md b/website/docs/developer/contributing.md new file mode 100644 index 0000000000..5c4df05a69 --- /dev/null +++ b/website/docs/developer/contributing.md @@ -0,0 +1,162 @@ +--- +title: Contributing +sidebar_label: Contributing +--- + + +Stratos is an open project and welcomes contributions. These guidelines are provided to help you understand how the project works and to make contributing smooth and fun for everybody involved. + +There are two main forms of contribution: reporting issues and performing code changes. + +## Reporting Issues + +If you find a problem with Stratos, report it using [GitHub issues](https://github.com/cloudfoundry/stratos/issues/new). + +Before reporting a new issue, please take a moment to check whether it has already been reported +[here](https://github.com/cloudfoundry/stratos/issues). If this is the case, please: + +- Read all the comments to confirm that it's the same issue you're having. +- Refrain from adding "same thing here" or "+1" comments. Just hit the + "subscribe" button to get notifications for this issue. +- Add a comment only if you can provide helpful information that has not been + provided in the discussion yet. + +When creating a new issue, make sure you include: + +1. As much detail as possible about your setup/environment +1. Steps to reproduce the issue/bug +1. What you expected to happen +1. What happened instead + +This information will help to determine the cause and prepare a fix as fast as possible. + +## Code Changes + +Code contributions come in various forms and sizes, from simple bug fixes to implementation +of new features. Before making any non-trivial change, get in touch with the Stratos developers first. This can prevent wasted effort later. + +To send your code change, use GitHub pull requests. The workflow is as follows: + + 1. Fork the project. + + 1. Create a branch based on `master`. + + 1. Implement your change, including tests and documentation. + + 1. Run tests to make sure your change didn't break anything. + + 1. Publish the branch and create a pull request. + + 1. Stratos developers will review your change and possibly point out issues. + Adapt the code under their guidance until all issues are resolved. + + 1. Finally, the pull request will get merged or rejected. + +See also [GitHub's guide on contributing](https://help.github.com/articles/fork-a-repo). + +If you want to do multiple unrelated changes, use separate branches and pull +requests. + +### Commits + +Each commit in the pull request should do only one thing, which is clearly +described by its commit message. Especially avoid mixing formatting changes and +functional changes into one commit. When writing commit messages, adhere to +[widely used +conventions](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). + +When the commit fixes a bug, put a message in the body of the commit message +pointing to the number of the issue (e.g. "Fixes #123"). + +### Pull requests and branches + +All work happens in branches. The master branch is only used as the target for pull +requests. + +During code review you often need to update pull requests. Usually you do that +by pushing additional commits. + +In some cases where the commit history of a pull request gets too cumbersome to +review or you need bigger changes in the way you approach a problem which needs +changing of commits you already did it's more practical to create a new pull +request. This new pull request often will contain squashed versions of the +previous pull request. Use that to clarify the changes contained in a pull +request and to make review easier. + +When you replace a pull request by another one, add a message in the +description of the new pull request on GitHub referencing the pull request it +replaces (e.g. "Supersedes #123"). + +Never force push commits. This changes history, can lead to data loss, and +causes trouble for people who have checked out the changes which are overwritten +by a force push. Don't waste time with thinking about if the force push in this +one particular case would be ok, just don't do it. + +### Check for assigned people + +We use Github Issues for submitting known issues (e.g. bugs, features, +etc.). Some issues will have someone assigned, meaning that there's already +someone that takes responsibility for fixing the issue. This is not done to +discourage contributions, rather to not step in the work that has already been +done by the assignee. If you want to work on a known issue with someone already +assigned to it, please contact the assignee first (e.g. by +mentioning the assignee in a new comment on the specific issue). This way you +can contribute with ideas, or even with code if the assignee decides that you +can step in. + +If you plan to work on a non assigned issue, please add a comment on the issue +to prevent duplicated work. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the change. Your +signature certifies that you wrote the change or otherwise have the right to pass +it on as an open-source change. The rules are pretty simple: if you can certify +the below (from [developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +Then you just add a line to each git commit message: + + Signed-off-by: Joe Smith + +Use your real name (sorry, no pseudonyms or anonymous contributions.) + +If you set your `user.name` and `user.email` git configs, you can sign your +commit automatically with `git commit -s`. diff --git a/docs/developers-guide-e2e-tests.md b/website/docs/developer/developers-guide-e2e-tests.md similarity index 90% rename from docs/developers-guide-e2e-tests.md rename to website/docs/developer/developers-guide-e2e-tests.md index dbac463428..d11776eb57 100644 --- a/docs/developers-guide-e2e-tests.md +++ b/website/docs/developer/developers-guide-e2e-tests.md @@ -1,4 +1,8 @@ -# E2E Tests +--- +id: developers-guide-e2e-tests +title: E2E Tests +sidebar_label: E2E Tests +--- The Stratos E2E test suite exercises the Stratos UI using protractor/web-driver. @@ -24,9 +28,9 @@ The tests require an instance of Cloud Foundry with the following: - A number of other Cloud Foundry entities To meet the above requirements we recommend running the Stratos CF E2E set up script which is kept up to date with the latest test requirements. -More information can be found [below](#Running-the-E2E-Set-up-Script) +More information can be found [below](#running-the-e2e-set-up-script) -Before running the E2E tests, you need to create a file named `secrets.yaml` in the root of the Stratos folder. An example template is included in [src/test-e2e/secrets.yaml.example](../src/test-e2e/secrets.yaml.example) - copy this to `secrets.yaml` and edit accordingly. +Before running the E2E tests, you need to create a file named `secrets.yaml` in the root of the Stratos folder. An example template is included in [src/test-e2e/secrets.yaml.example](https://github.com/cloudfoundry/stratos/blob/master/src/test-e2e/secrets.yaml.example) - copy this to `secrets.yaml` and edit accordingly. If you want to run the tests in headless Chrome, add the following to the secrets file: @@ -35,7 +39,7 @@ headless: true ``` ## Running the E2E Set up Script -The script can be found in [deploy/tools/init-cf-for-e2e.sh](../deploy/tools/init-cf-for-e2e.sh) +The script can be found in [deploy/tools/init-cf-for-e2e.sh](https://github.com/cloudfoundry/stratos/blob/master/deploy/tools/init-cf-for-e2e.sh) ### Minimum Requirements - CF CLI @@ -107,7 +111,7 @@ Given the output of the script, the following template can be used to update the ### Tidying up test generated CF entities If tests are stopped before completing or fail to clean old test artifacts will exist in the CF. To clean some of these please see the script -at [deploy/ci/automation/e2e-clean-remnants.sh](../deploy/ci/automation/e2e-clean-remnants.sh) +at [deploy/ci/automation/e2e-clean-remnants.sh](https://github.com/cloudfoundry/stratos/blob/master/deploy/ci/automation/e2e-clean-remnants.sh) ## Running the tests diff --git a/docs/developers-guide-env-tech.md b/website/docs/developer/developers-guide-env-tech.md similarity index 98% rename from docs/developers-guide-env-tech.md rename to website/docs/developer/developers-guide-env-tech.md index 7e22201b90..76918f9fba 100644 --- a/docs/developers-guide-env-tech.md +++ b/website/docs/developer/developers-guide-env-tech.md @@ -1,4 +1,8 @@ -# Stratos Tech + Developer Environment +--- +id: developers-guide-env-tech +title: Stratos Tech + Developer Environment +sidebar_label: Dev Environment +--- ## ES6 diff --git a/website/docs/developer/frontend-tests.md b/website/docs/developer/frontend-tests.md new file mode 100644 index 0000000000..d5380411b6 --- /dev/null +++ b/website/docs/developer/frontend-tests.md @@ -0,0 +1,73 @@ +--- +title: Frontend Tests +sidebar_label: Tests +--- + +## Test + +### Lint + +Run `npm run lint` to execute tslint lint checking. + +### Unit tests + +Run `npm test` to execute the unit tests via [Karma](https://karma-runner.github.io). Coverage information can be found in `./coverage` + +To execute an individual package run `ng test `. To execute the tests again automatically on code changes add `--watch=true` + +> **NOTE** npm test will search for chrome on your path. If this is not so please set an env var CHROME_BIN pointing to your executable +(chromium is fine too). + +### End-to-end tests + +Run `npm run e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). + +Run `npm run e2e-dev` to execute end-to-end tests against a locally running instance on `https://localhost:4200` + +More information on the E2E tests and pre-requisites for running them is available here - [E2E Tests](developers-guide-e2e-tests.md). + +### Code Climate + +We use [Code Climate](https://codeclimate.com/github/cloudfoundry-incubator/stratos) to check for general code quality issues. This executes against Pull +Requests on creation/push. + +#### Running Code Climate locally +> Generally we would not advise doing this and just rely on the code climate gate to run when pull requests are submitted + +To run locally see instructions [here](https://github.com/codeclimate/codeclimate) to install Code Climate CLI +and engine via docker. Once set ensure you're in the root of the project and execute the following (it may take a while) + +``` +codeclimate analyze +``` + +> **NOTE** Unfortunately this highlights all current issues and not those that are the diff between any master and feature branch. Analyze +can be ran against a single/sub set of files, again with all current issues, but a little more digestible. + +``` +codeclimate analyze +``` + +In a feature branch to compare files that have changed to master, for instance, use the following + +``` +git checkout feature-branch-A +codeclimate analyze $(git diff --name-only master) +``` + +You can also run the above command via npm + +``` +npm run climate +``` + +### Stratos Continue Integration +For each new pull request and any subsequent pushes to it the following actions are executed +- Code quality analysis via Code Climate - https://codeclimate.com/ +- Jenkins CI run, covering.. + - Frontend lint check + - Backend lint check + - Frontend unit tests + - Backend unit tests + - End to end tests +- Security anaylsis via Snyk - https://snyk.io/ diff --git a/website/docs/developer/frontend.md b/website/docs/developer/frontend.md new file mode 100644 index 0000000000..2c5416e0c4 --- /dev/null +++ b/website/docs/developer/frontend.md @@ -0,0 +1,90 @@ +--- +title: Frontend Development +sidebar_label: Overview +--- + +## Introduction to the stack + +Have a look through the [Env + Tech](developers-guide-env-tech.md) page to get acquainted with some of the new technologies used in v2. +These include video's, tutorials and examples of Angular 2+, Typescript and Redux. There's also some advice on helpful plugins to use if +using Visual Studio Code. If you feel comfortable with these and are happy with your dev environment please skip straight to +[Set up Dependencies](#set-up-dependencies) + +## Set up Dependencies + +* Set up a Stratos backend - The frontend cannot run without a backend. Both backend and frontend exist in this same repo. + * Don't need to make changes to the backend code? To set up a backend run through the [deploy section](../deploy/overview), + choose a deployment method and bring one up. These deployments will bring up the entire backend, including api service and database + along with a V2 frontend. + * Need to make changes to the backend code? Follow the [Backend Development](backend) set up guide +* Install [NodeJs](https://nodejs.org) (minimum node version 12.13.0) +* Install [Angular CLI](https://cli.angular.io/) - `npm install -g @angular/cli` + +## Configuration + +Configuration information can be found in two places + +* `./proxy.conf.js` + * In new forks this is missing and needs to be created using `./proxy.conf.template.js` as a template. + * Contains the address of the backend. Which will either be... + * If the backend is deployed via the instructions in the [deploy section](../deploy/overview) + the url will be the same address as the V1 console's frontend address. For instance `https://localhost` would translate to + ``` + const PROXY_CONFIG = { + "/pp": { + "target": { + "host": "localhost", + "protocol": "https:", + "port": 443 + }, + "secure": false, + "changeOrigin": true, + "ws": true, + } + ``` + * If the backend is running locally using the instructions in [Backend Development](backend), the url will local host + with a port of the `CONSOLE_PROXY_TLS_ADDRESS` value from `src/jetstream/config.properties`. By default this will be 5445. For + instance + ``` + const PROXY_CONFIG = { + "/pp": { + "target": { + "host": "localhost", + "protocol": "https:", + "port": 5443 + }, + "ws": true, + "secure": false, + "changeOrigin": true, + } + } + ``` +* `./src/frontend/environments/environment.ts` for developer vs production like config + * This contains more general settings for the frontend and does not usually need to be changed + +## Run the frontend + +1. (First time only) Copy `./proxy.conf.template.js` to `./proxy.conf.js` and update with required Jetstream url (see above for more info) +1. Run `npm install` +1. Run `npm start` for a dev server. (the app will automatically reload if you change any of the source files) + * If this times out please use `npm run start-high-mem` instead + * To change the port from the default 4200, add `-- --port [new port number]` + * To stop the automatic reload every time a resource changes add `-- --live-reload false` + * To do both the above use `-- --live-reload false --port [new port number]` +1. Navigate to `https://localhost:4200/`. The credentials to log in will be dependent on the Jetstream the console points at. Please refer + to the guides used when setting up the backend for more information + +## Build + +Run `npm run build` to build the project. + +The build artefacts will be stored in the `dist/` directory. This will output a production build of the application. + +## Creating angular items via angular cli + +To create a new angular component run `ng generate component component-name`. You can use a similar command to create other types of angular +items `ng generate `. + +## Theming + +We use the angular material theming mechanism. See [here](https://material.angular.io/guide/theming-your-components) for more information about theming new components added to stratos. diff --git a/website/docs/developer/introduction.md b/website/docs/developer/introduction.md new file mode 100644 index 0000000000..8e617a0489 --- /dev/null +++ b/website/docs/developer/introduction.md @@ -0,0 +1,38 @@ +--- +title: Developing the Stratos Console +sidebar_label: Stratos Development +--- + +1. [Introduction](#introduction) +1. [Frontend Development](frontend) +1. [Backend Development](backend) + +## Introduction + +Stratos comprises of two main components: + +- A front-end UI that runs in your web browser. This is written in [Typescript](https://www.typescriptlang.org/) and uses the [Angular](https://angular.io/) framework. +- A back-end that provides a web-based API to the front-end. This is written in Go. + +Depending on what you are contributing, you will need to develop with the front-end, back-end or both. + +## Building and running the Frontend and Backend Locally + +For a quick-start to get Stratos built and running locally on a development system, follow the steps below. + +You will need to have `go` and `nodejs` installed in your development environment. + +``` +git clone https://github.com/cloudfoundry/stratos.git +cd stratos +npm install +npm run build +npm run build-backend +./src/jetstream/jetstream +``` + +This will build both the frontend and backend and run the backend in a mode where it will also serve the static resources for the frontend. + +You can open a web browser and navigate to (https://127.0.0.1:5443) and login with username `admin` and password `admin`. + + diff --git a/docs/backend-plugins.md b/website/docs/extensions/backend.md similarity index 98% rename from docs/backend-plugins.md rename to website/docs/extensions/backend.md index 4aba144c68..904880c895 100644 --- a/docs/backend-plugins.md +++ b/website/docs/extensions/backend.md @@ -1,4 +1,7 @@ -# Backend Plugins +--- +title: Backend Plugins +sidebar_label: Backend Plugins +--- This document provides a brief outline for extending the Stratos backend (Jetstream). diff --git a/docs/customizing.md b/website/docs/extensions/customizing.md similarity index 77% rename from docs/customizing.md rename to website/docs/extensions/customizing.md index e81f9ebabd..b85b0dde1c 100644 --- a/docs/customizing.md +++ b/website/docs/extensions/customizing.md @@ -1,36 +1,11 @@ -# Customizing Stratos - -Stratos provides a mechanism for customization - the following customizations are currently supported: - -- Changing the theme colors -- Changing certain image assets (favorite icon, login background and logo) -- Overriding styles -- Adding new functionality -- Changing the initial loading indicator - -# Migrating to Stratos V4 Customization -In V4 there are breaking customization changes. These changes allow a much improved approach to extensions by opening the door to npm style plugins. -To aid in migrating we've provided these instructions. - -1) Before updating to the latest code... - 1) Run `npm run customize-reset` to remove all previously created sym links. - 2) Read through the customization documentation below to get a better understanding of the new process. -1) Update your codebase with the desired v4 code. -1) Run `npm install` (only required first time, this will ensure you have the required version of Angular). -1) Change directory to `./build/tools/v4-migration` and run the migration script `./migrate.sh`. - - This will copy your customizations from `custom-src` to a new Angular package `src/frontend/packages/custom_extensions`. -1) Check that the new package exports your custom module and if applicable your custom-routing module. - - The migrate script should do this in `src/frontend/packages/custom_extensions/src/public-api.ts`. -1) Check that your ts config file defines the public api file. - - `src/tsconfig.json` file's `compilerOptions/paths` section should contain something like `"@custom/extensions": ["frontend/packages/custom_extensions/src/public-api.ts"]`. -1) Check that your new package's package.json defines your custom module and if application custom-routing module. - - See `src/frontend/packages/suse_extensions/package.json` file's `stratos` section. - - Note your `routingModule` entry label should not have a preceding `_`. -1) Build Stratos in your usual way, for instance `npm run build`. - - It could be that this fails due to TypeScript import issues, if so go through these and fix. - - During build time the custom packages will be discovered and output, see section starting `Building with these extensions`. These should contain the modules your require. -1) Run Stratos your usual way. Ensure you can navigate to all your custom parts. -1) Once you are happy everything works as intended remove the old `./custom-src` directory and commit you changes. +--- +id: customizing +title: Customizing Stratos +sidebar_label: Customizing Stratos +--- + + +> This document is out of date and is in the process of being refreshed. ## Approach @@ -146,7 +121,7 @@ When you perform an `npm install` or explicitly run `npm run customize`, the cus Within the `custom-src/frontend/app/custom` folder you must create a module in the file `custom.module.ts` named `CustomModule` - this will be imported into the Stratos application and is the mechanism by which you can add custom code to the front-end. -We currently expose the following extension points in the Stratos UI: +We currently expose the following extension points in Stratos: - Changing the component to use for the login screen - Adding new items to the side navigation menu @@ -155,7 +130,7 @@ We currently expose the following extension points in the Stratos UI: We use Decorators to annotate components to indicate that they are Stratos extensions. -See [Extensions](extensions.md) for more detail and examples of front-end extensions. +See [Extensions](../extensions/frontend) for more detail and examples of front-end extensions. ### Changing the Initial Loading Indicator diff --git a/docs/extensions.md b/website/docs/extensions/frontend.md similarity index 81% rename from docs/extensions.md rename to website/docs/extensions/frontend.md index 918c25df18..a253e906ef 100644 --- a/docs/extensions.md +++ b/website/docs/extensions/frontend.md @@ -1,4 +1,7 @@ -# Front-end Extensions +--- +title: Frontend Extensions +sidebar_label: Frontend Extensions +--- An example illustrating the various front-end extension points of Stratos is included in the folder `examples/custom-src`. @@ -10,9 +13,9 @@ Next, run the customization script (this is done automatically when you do an `n npm run customize ``` -You can now run Stratos locally to see the customizations - see the [Developer's Guide](developers-guide.md) for details. +You can now run Stratos locally to see the customizations - see the [Developer's Guide](../developer/frontend) for details. -For a walk-through of extending Stratos, see [Example: Adding a Custom Tab](#example:-adding-a-custom-tab). +For a walk-through of extending Stratos, see [Example: Adding a Custom Tab](#example-adding-a-custom-tab). ## Extension Points @@ -76,25 +79,12 @@ 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: 1. Create a new component that will provide the tab contents -2. Ensure that your component is declared with the `ExtensionService` in the imports of your custom module, for example: -``` - @NgModule({ - imports: [ - ExtensionService.declare([ - ExtensionComponent, - ]) - ], - declarations: [ - ExtensionComponent - ] - }) -``` - +2. Ensure that your component is included in the `EntryComponent` section of your custom module 2. Decorate the component with the `StratosTab` decorator, for example: ``` @@ -107,13 +97,13 @@ The approach for all of these is the same: Where: -- indicates where the tab should appear and can be: +- < TYPE > indicates where the tab should appear and can be: - StratosTabType.Application - Application View - StratosTabType.CloudFoundry - Cloud Foundry view - StratosTabType.CloudFoundryOrg - Cloud Foundry Org view - StratosTabType.CloudFoundrySpace - Cloud Foundry Space view --