From e12f60fe9c13173a9696d3ac9e95a221e50082e4 Mon Sep 17 00:00:00 2001 From: Richard Cox Date: Fri, 7 Aug 2020 18:17:02 +0100 Subject: [PATCH] Update developer docs (#4489) * 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 * Apply new theming process to acme example * First pass at customization docs, most of themeing done * Final pass at customization docs * Update base README, point to website * Update developer docs Still need an overhall, but updated to remove incorrect data and apply website context Co-authored-by: Veerapuram Varadhan Co-authored-by: Neil MacDougall Co-authored-by: Neil MacDougall 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> --- website/docs/developer/backend.md | 6 +- .../developer/developers-guide-e2e-tests.md | 10 ++- website/docs/developer/frontend.md | 87 ++++++++----------- website/docs/developer/introduction.md | 19 ++-- website/sidebars.js | 2 +- 5 files changed, 55 insertions(+), 69 deletions(-) diff --git a/website/docs/developer/backend.md b/website/docs/developer/backend.md index f54dac53c0..d8b2e7bc15 100644 --- a/website/docs/developer/backend.md +++ b/website/docs/developer/backend.md @@ -42,7 +42,7 @@ 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 +By default, the configuration in file `./src/jetstream/config.dev` will be used. These can be changed by environment variables or an overrides file. ##### Environment variable @@ -68,7 +68,7 @@ If you have a custom uaa, ensure you have set the following environment variable ##### Config File -To easily persist configuration settings copy `src/jetstream/default.config.properties` to `src/jetstream/config.properties`. The backend will load its +To easily persist configuration settings copy `src/jetstream/config.dev` 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. @@ -101,7 +101,7 @@ this process, validating that the UAA address and credentials are correct. It wi Execute the following file from `src/jetstream` ``` -jetstream +./jetstream ``` You should see the log as the backend starts up. You can press CTRL+C to stop the backend. diff --git a/website/docs/developer/developers-guide-e2e-tests.md b/website/docs/developer/developers-guide-e2e-tests.md index d11776eb57..03d17b1643 100644 --- a/website/docs/developer/developers-guide-e2e-tests.md +++ b/website/docs/developer/developers-guide-e2e-tests.md @@ -10,7 +10,7 @@ The tests require a Stratos instance to be running (front-end and back-end) and Developers' should be aware that: -- The E2E tests are destructive on the Stratos system being tested - since they test endpoint registration, they will un-register any existing endpoints +- The E2E tests are destructive on the Stratos system being tested - since they test endpoint registration, they will un-register any existing endpoints. - The E2E tests will create orgs, spaces, applications, routes, etc in the Cloud Foundry instance that is specified. Tests should automatically tidy up afterwards unless stopped abruptly. ## Pre-requisites @@ -28,7 +28,7 @@ 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](https://github.com/cloudfoundry/stratos/blob/master/src/test-e2e/secrets.yaml.example) - copy this to `secrets.yaml` and edit accordingly. @@ -117,7 +117,11 @@ at [deploy/ci/automation/e2e-clean-remnants.sh](https://github.com/cloudfoundry/ To run the tests against an instance of Stratos execute ``` -npm run e2e -- --dev-server-target= --base-url= ng e2e --dev-server-target= --base-url= +``` +If running Stratos on `https://127.0.0.1:4200` then instead execute +``` +npm run e2e-dev ``` diff --git a/website/docs/developer/frontend.md b/website/docs/developer/frontend.md index 2c5416e0c4..17c1e7b037 100644 --- a/website/docs/developer/frontend.md +++ b/website/docs/developer/frontend.md @@ -5,66 +5,25 @@ 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) +Before making changes to the frontend code you should be familiar with -## Set up Dependencies +1. Angular +1. Typescript / ES6 +1. Redux / NGRX / Observables +1. Node / NPM -* 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` +There are a some introduction style resources [here](/docs/developer/developers-guide-env-tech.md). There's also some advice on helpful [VS code plugins](/docs/developer/developers-guide-env-tech#vs-code-plug-ins). If you feel comfortable with these and are happy with your dev environment please skip straight to +[Set up Dependencies](#set-up-dependencies). -## Configuration +## Set up Dependencies -Configuration information can be found in two places +* Set up a Stratos backend. Both backend and frontend exist in this same repo. Follow the [Backend Development](/docs/developer/introduction#build--run-locally) set up guide. +* Install [NodeJs](https://nodejs.org) (if not already install) (minimum node version 12.13.0) +* Install [Angular CLI](https://cli.angular.io/) (if not already install) - `npm install -g @angular/cli` -* `./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 @@ -76,6 +35,8 @@ Configuration information can be found in two places ## Build +> The normal dev cycle does not require a direct 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. @@ -88,3 +49,25 @@ items `ng generate To develop the frontend we recommend reading through the [frontend](/docs/developer/frontend) doc. This includes a faster way to run Stratos and see your changes. +> Additional back end docs are available [here](/docs/developer/backend) before making any changes to the code. diff --git a/website/sidebars.js b/website/sidebars.js index e286c79021..03b790c3e4 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -39,8 +39,8 @@ module.exports = { 'developer/backend', ] }, + 'developer/developers-guide-e2e-tests', 'developer/developers-guide-env-tech', - 'developer/developers-guide-e2e-tests' ], 'Extending Stratos': [ 'extensions/introduction',