Skip to content

Commit

Permalink
Update developer docs (cloudfoundry#4489)
Browse files Browse the repository at this point in the history 
* Fixes cloudfoundry#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 (cloudfoundry#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 (cloudfoundry#4440)

* Show all favorites for the endpoint favorite if there is only one

* Missing changes

* Merge downstream - JSON Viewer with dark mode & Header Fixes (cloudfoundry#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 (cloudfoundry#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 (cloudfoundry#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 (cloudfoundry#4459)

- switch from TRAVIS_PULL_REQUEST_SLUG to TRAVIS_REPO_SLUG

* Convert Client Secret Input Fields to `password` (cloudfoundry#4455)

* Insecure tlsv10 and tlsv11 ciphers in Stratos UI, bsc#1173295 (#411) (cloudfoundry#4460)

Co-authored-by: Michal Jura <mjura@users.noreply.github.com>

* [Security] Bump codecov from 3.7.0 to 3.7.1 (cloudfoundry#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](codecov/codecov-node@v3.7.0...v3.7.1)

Signed-off-by: dependabot-preview[bot] <support@dependabot.com>

Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com>

* Bump lodash from 4.17.15 to 4.17.19 (cloudfoundry#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](lodash/lodash@4.17.15...4.17.19)

Signed-off-by: dependabot[bot] <support@github.com>

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 <v.varadhan@gmail.com>
Co-authored-by: Neil MacDougall <neil.macdougall@suse.com>
Co-authored-by: Neil MacDougall <nmacdougall@suse.com>
Co-authored-by: Neil MacDougall <nwmac@users.noreply.github.com>
Co-authored-by: Michal Jura <mjura@users.noreply.github.com>
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>
  • Loading branch information
@richard-cox @vvaradhan
@nwmac @mjura @dependabot-preview @dependabot
8 people committed Aug 7, 2020
1 parent b713c78 commit e12f60f
Show file tree
Hide file tree
Showing 5 changed files with 55 additions and 69 deletions.
6 changes: 3 additions & 3 deletions website/docs/developer/backend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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.
Expand Down
10 changes: 7 additions & 3 deletions website/docs/developer/developers-guide-e2e-tests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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=<URL of stratos
STRATOS_E2E_BASE_URL=<URL of stratos> ng e2e --dev-server-target= --base-url=<URL of stratos>
```
If running Stratos on `https://127.0.0.1:4200` then instead execute
```
npm run e2e-dev
```


Expand Down
87 changes: 35 additions & 52 deletions website/docs/developer/frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -88,3 +49,25 @@ items `ng generate <directive|pipe|service|class|guard|interface|enum|module> <n
## 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.


## Additional Information

### Extensions

Documentation on extensions can be found [here](/docs/extensions/introduction). From a developers perspective extensions are managed by npm packages.
The default set are in `./src/frontend/packages`, any package added directly here will be automatically included by the build.

At build time the Stratos Devkit (`./src/frontend/packages/devkit`) will ensure all packages are imported correctly and theming, both component and console level, are applied correctly.
The devkit is automatically built in `postinstall` after `npm install` is ran. To directly build it `npm run dev-setup` can be executed.

### Configuration

Configuration information can be found in two places

* `./proxy.conf.js`
* Informs the frontend where the backend is
* `./src/frontend/packages/core/src/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
* `config.properies`
* Backend configuration
19 changes: 9 additions & 10 deletions website/docs/developer/introduction.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,20 @@
---
title: Developing the Stratos Console
sidebar_label: Stratos Development
sidebar_label: Getting Started
---

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.
- A back-end that provides a web-based API to the front-end. This is written in [Go](https://golang.org/).

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
## Build & Run Locally

For a quick-start to get Stratos built and running locally on a development system, follow the steps below.
For a quick-start to get Stratos front and back ends 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.

Expand All @@ -28,11 +24,14 @@ cd stratos
npm install
npm run build
npm run build-backend
./src/jetstream/jetstream
cd 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.
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`.

> 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.
2 changes: 1 addition & 1 deletion website/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down

0 comments on commit e12f60f

Please sign in to comment.