From 9b571c6718b9658491d8cdc4c2569c5c5e662e7a Mon Sep 17 00:00:00 2001 From: Richard Cox Date: Mon, 12 Feb 2018 16:33:39 +0000 Subject: [PATCH] Remove incorrect/missleading documentation left over from v1 (#1608) - We should update these in the future - We also need to validate all deploy types in new branch/folder structure --- README.md | 6 +- deploy/cloud-foundry/README.md | 33 +--- docs/developers-guide.md | 50 +++++- docs/development.md | 284 --------------------------------- docs/features.md | 2 + docs/i18n.md | 91 +---------- 6 files changed, 62 insertions(+), 404 deletions(-) delete mode 100644 docs/development.md diff --git a/README.md b/README.md index ac8a59471a..49c6cef10e 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Stratos is an Open Source Web-based UI (Console) for managing Cloud Foundry. It allows users and administrators to both manage applications running in the Cloud Foundry cluster and perform cluster management tasks. -![Stratos Application view](docs/images/screenshots/app-wall.png) + ## Deploying Stratos @@ -35,8 +35,8 @@ You can access the UI on `https://localhost:4443` ## Project Planning We use [ZenHub](https://zenhub.com) for project planning. Feel free to head over to the [Boards](https://github.com/SUSE/stratos#boards) -tab and have a look through our pipelines and milestones. Please note in order to view the ZenHub Boards tab you will need the [ZenHub -browser extension](https://www.zenhub.com/extension). +tab and have a look through our pipelines and milestones. Please note in order to view the Github ZenHub Boards tab you will need the [ZenHub +browser extension](https://www.zenhub.com/extension). Alternatively, to view the planning board without the extension visit our [ZenHub Project Page](https://app.zenhub.com/workspace/o/cloudfoundry-incubator/stratos/boards) ## Further Reading diff --git a/deploy/cloud-foundry/README.md b/deploy/cloud-foundry/README.md index dc8639f020..767e16e919 100644 --- a/deploy/cloud-foundry/README.md +++ b/deploy/cloud-foundry/README.md @@ -2,11 +2,11 @@ ## Deployment Steps -The quickest way to install Stratos UI is to deploy it as a Cloud Foundry application. To do so, clone the `stratos-ui` repository, cd into the newly cloned repository and push to Cloud Foundry. This can be done with: +The quickest way to install Stratos UI is to deploy it as a Cloud Foundry application. 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/SUSE/stratos-ui.git -cd stratos-ui +git clone https://github.com/cloudfoundry-incubator/stratos +cd stratos cf push ``` @@ -27,27 +27,8 @@ Note: 1. You need the cf CLI command line tool installed and available on the path. 2. 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. -3. You may need to configure Application Security Groups on your Cloud Foundry Cluster in order that Stratos UI can communicate with the Cloud Foundry API. See [below](#application-security-groups) for more information. -4. The Stratos UI 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). - -## Enable Endpoints Dashboard to register additional Cloud Foundry endpoints - -To enable the dashboard add the environment variable 'FORCE_ENDPOINT_DASHBOARD' to the manifest before the call to 'cf push' is made. For example - - ``` - applications: - - name: console - memory: 256M - disk_quota: 256M - host: console - timeout: 180 - buildpack: https://github.com/SUSE/stratos-buildpack - health-check-type: port - env: - FORCE_ENDPOINT_DASHBOARD: true - ``` - ->**NOTE** This step, on it's own, is meant for demonstration purposes only. Registered endpoints will be lost if the app is restarted and each app instance will have it's own lists. To remove these caveats see the section 'Associate Cloud Foundry database service' below. +3. 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. +4. 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). ## Associate Cloud Foundry database service Follow instructions [here](db-migration/README.md). @@ -149,7 +130,7 @@ applications: disk_quota: 256M host: console timeout: 180 - buildpack: https://github.com/SUSE/stratos-buildpack + buildpack: https://github.com/cloudfoundry-incubator/stratos-buildpack health-check-type: port env: CF_API_URL: https://<>> @@ -166,7 +147,7 @@ applications: disk_quota: 256M host: console timeout: 180 - buildpack: https://github.com/SUSE/stratos-buildpack + buildpack: https://github.com/cloudfoundry-incubator/stratos-buildpack health-check-type: port env: CF_API_FORCE_SECURE: true diff --git a/docs/developers-guide.md b/docs/developers-guide.md index d3528a0435..37892d4540 100644 --- a/docs/developers-guide.md +++ b/docs/developers-guide.md @@ -116,5 +116,53 @@ Run `npm run e2e` to execute the end-to-end tests via [Protractor](http://www.pr ## Backend Development The backend (more informally called the portal-proxy or 'pp' for short) is still to be ported over from V1 of -[Stratos](https://github.com/SUSE/stratos-ui). Once that's completed come back and check out this section for instructions on how to +[Stratos](https://github.com/cloudfoundry-incubator/stratos). Once that's completed come back and check out this section for instructions on how to make changes to it. + +WIP + +### Getting started + +The portal-proxy is the back-end for the Console UI. It is written in Go. + +### Automatically register and connect to an existing endpoint +To automatically register a Cloud Foundry add the environment variable below + +> **Note** On log in the console will also attempt to auto-connect to the cloud foundry using + the username/password provided. + +``` +AUTO_REG_CF_URL= +``` + +This env var can be set in `outputs/config.properties` if running the backend locally in the host machine, `./deploy/proxy.env` if running in docker-compose or `./manifest` if in cf push. + +> **NOTE** WIP Instructions! + +#### Introduction +* Golang +* Dependency Management (Glide) + +#### Dependencies +* go + * GOPATH, GOBIN env vars set +* glide +* UAA instance + +#### Running portal-proxy in a container +* Follow instructions in the deploy/docker-compose docs +* To apply changes (build and update docker image) simply run `deploy/tools/restart_proxy.sh` + +#### Running "like a dev" + +1. Set up developer certs + - Execute `deploy/tools/generate_cert.sh` + - Copy `portal-proxy-output/dev-certs` to `./` +1. Update `build/dev_config.json` with `"localDevBuild": true` +1. Run `gulp local-dev-build` +1. cd ./outputs +1. Run `gulp build-backend` +1. Update `config.propeties` and ensure that.. + - the UAA points to a valid instance + - the `CONSOLE_CLIENT` and `CONSOLE_ADMIN_SCOPE` are valid in the UAA instance +1. Run `portal-proxy` diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index 40cba69e92..0000000000 --- a/docs/development.md +++ /dev/null @@ -1,284 +0,0 @@ -# Developing the Stratos Console - -> **Note:** This document is work in progress. - - -The Stratos Console UI provides a single comprehensive and ubiquitous user -experience for: discovering, composing, developing and managing Cloud Native -workloads which are hosted in a myriad of: public, managed and private -cloud/compute providers. - -1. [Working on the front-end component](#working-on-the-front-end-component) -2. [Working on the back-end component](#working-on-the-backend-component) -3. [Testing](#testing) - -## Dependencies - -### Node -Please check the `engine` entry of the package.json file for the required node version. - > **Note:** To manage node versions we recommend using [nvm](https://github.com/creationix/nvm) - -## Components - -The top-level repository contains three folders worth calling out: - -Folder | Description --------|------------ -build | Contains build scripts (mainly gulp-based) for both the backend and frontend -components | Contains the source code for the Console -deploy | Contains scripts and artifacts for deploying the Console. - -The Console code can be found in the [components](../components) folder. The following components are currently included: - -Component Name | Description ----------------|------------ -about-app | Provides an "about" view for the Console -app-core | Contains core functionality, such as login and navigation -app-framework | Providers a set of UI widgets and utilities -app-theme | Style information for the app-framework -cloud-foundry | All Cloud Foundry specific code -cloud-foundry-hosting | Specific component used for hosting the Console as an app in a single Cloud Foundry -endpoints-dashboard | Manage Console endpoints, specifically Cloud Foundry's. The inclusion allows additional Cloud Foundry endpoints to be added -suse-branding | Overrides styles to show the Console with SUSE branding - -### Component architecture - -Components can include both frontend and backend code. The source code for these sits together under a single component folder. - -The Console Frontend is written using AngularJS and the backend written in Go. - -The Console build determines the location of the frontend and backend code via a configuration file -named `[component name].component.json`. -When no frontend configuration is found in *.component.json it is assumed the component is purely for the frontend and that its source -code sites directly in the component folder, father than a `frontend` subfolder. - -### Including your own components -Other components can be included to add additional items to the navigation bar and their associated content. This can include additional types of 'endpoints' (an existing endpoint for example is Cloud Foundry). Instructions on how to carry out this will be added at a later date. - -## Working on the front end component - -### Source Code Structure - -The frontend code is split into component directories as listed above. -The standard set of components that exist in the console contain functionality -to manage Cloud Foundry instances and their applications. - -The frontend code is usually found within a `frontend` folder and contains -a structure such as that in app-core/frontend component, for example: -``` -|-- frontend -| |-- assets -| |-- i18n -| | -- en -| |-- src -| | |-- api -| | |-- model -| | |-- utils -| | |-- view -| |-- test -| `-- index.html -|-- app-core.component.json -`-- bower.json -``` - -Directory | Contains -----------|------------ -assets | Any images required by the front end -i18n | Internationalization strings per locale. By default the console contains English (US) -src | Javascript, html and scss related to the component -test | Unit tests for the component - -> **Note:** The bower.json is in the root of the component - -### Style Sheets -The frontend defines styles in SCSS which is converted to CSS at build time. -Each component is responsible for specifying it's root scss as a 'main' file -in it's bower.json. From this all other -component scss are gathered. - -### Build Process -The build process uses gulp, see the the root gulpfile.js. Below is a list -of important gulp tasks. - -Gulp task name | Description -----------|------------ -clean | Removes the dist folder -dev | Executes a developer build and serves the console via browser sync -run | Executes a production build and serves the console via express -lint | Executes linting via eslint. See ./.eslintrc for rules - -> **Note:** When using the `dev` task, web sockets do not get forwarded, so log streaming and ssh access will not work - use the `run` task to test these. - -Some tasks can be accessed via npm, by running `npm script target` along with additional test -functionality: - -NPM script name | Description -----------------|------------ -lint | Same as gulp lint -coverage | Executes both unit and e2e tests and provides a combined coverage report in `./out/coverage-report` -gate-check | Executes lint and unit tests, very handy to use before creating a PR -e2e | Executes end to end tests via protractor, also handy to use before creating a PR. Screenshots of the console for each failure can be found in ./out/e2e-failures -test | Executes unit tests - - -### Run the frontend via gulp - -#### Requirements -The Console backend must be up and contactable by the developers machine. -This can be achieved via any of the methods -described in the [deploy](../deploy/README.md) instructions. - -#### Configuration -The Console frontend must know the address of the backend. This can be -set by creating the file ./build/dev_config.json -with contents such as -``` -{ - "pp": "/pp" -} -``` - -For example, if the console was deployed and accessible via `https://localhost` - -the following configuration should be used -``` -{ - "pp": "https://localhost/pp" -} -``` -Run the following commands to install the dependencies -``` -$ npm install -$ bower install - -``` - -#### Run -To run the frontend with bits as if it were production (uses minified resources) execute ... -``` -$ gulp run -``` - -To run the frontend in development mode (uses non-minified resources and serves via browsersync) execute ... -``` -$ gulp dev -``` - -In both cases the console should be available via https://localhost:3100 - -> **Note:** If you see the following error when running 'gulp dev' you may need to increase your OS ulimit. -``` -Error: ENFILE: file table overflow, scandir ; - at Error (native) --bash: /dev/null: Too many open files in system -``` - -### Linting -We use eslint to executing linting. To run these execute... -``` -$ gulp lint -``` - - -### Creating a successful Pull Request in github -For every new pull request, or commit to an existing request, the CI will -run a build against the requests HEAD. Before creating a PR or pushing to -one please ensure the following two requests execute successfully - -``` -$ npm run gate-check -``` -(lint + unit tests) - -``` -$ npm run e2e -``` -(e2e tests) - -## Working on the backend component - -### Getting started - -The portal-proxy is the back-end for the Console UI. It is written in Go. - -### Automatically register and connect to an existing endpoint -To automatically register a Cloud Foundry add the environment variable below - -> **Note** On log in the console will also attempt to auto-connect to the cloud foundry using - the username/password provided. - -``` -AUTO_REG_CF_URL= -``` - -This env var can be set in `outputs/config.properties` if running the backend locally in the host machine, `./deploy/proxy.env` if running in docker-compose or `./manifest` if in cf push. - -> **NOTE** WIP Instructions! - -#### Introduction -* Golang -* Dependency Management (Glide) - -#### Dependencies -* go - * GOPATH, GOBIN env vars set -* glide -* UAA instance - -#### Running portal-proxy in a container -* Follow instructions in the deploy/docker-compose docs -* To apply changes (build and update docker image) simply run `deploy/tools/restart_proxy.sh` - -#### Running "like a dev" - -1. Set up developer certs - - Execute `deploy/tools/generate_cert.sh` - - Copy `portal-proxy-output/dev-certs` to `./` -1. Update `build/dev_config.json` with `"localDevBuild": true` -1. Run `gulp local-dev-build` -1. cd ./outputs -1. Run `gulp build-backend` -1. Update `config.propeties` and ensure that.. - - the UAA points to a valid instance - - the `CONSOLE_CLIENT` and `CONSOLE_ADMIN_SCOPE` are valid in the UAA instance -1. Run `portal-proxy` - -#### Tests - -##### Unit Testing - - -## Testing - -### Front End Unit Tests -Unit test are written via jasmine and executed in karma. To run these execute... -``` -$ npm test -``` - -### End to End Tests -To run e2e tests a cloud foundry with specific orgs, spaces and users is required. - -To set this up -1. Ensure the cf cli tool is installed. See https://github.com/cloudfoundry/cli -2. cf tool has targeted the cf instance and logged in (cf api, cf login) -3. Execute the following script to set up the SUSE org, dev space and e2e user - -**NOTE** This will also create an application which will continually output log statements. This will be used to test - the log reader. -``` -$ ./test/e2e/config-cf.sh -``` -4. Copy ./build/secrets.json.sample to ./build/secrets.json and update cloudFoundry url and cf admin username/password -5. Execute the tests via... -``` -$ npm run e2e -``` - -#### Continuous Integration - -Pull request submitted to the stratos-ui project will run through -frontend unit tests, backend unit tests and integration tests. The -concourse server which executes these is currently not available -externally. The result however can still be seen by the usual -indications posted by github to the PR's page. diff --git a/docs/features.md b/docs/features.md index d1d3194d88..596729caa3 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,5 +1,7 @@ # Features +> **NOTE** This branch is a work-in-progress Angular 2.x version of Stratos. For the current Angular 1 based version see [https://github.com/cloudfoundry-incubator/stratos/tree/master](https://github.com/cloudfoundry-incubator/stratos/tree/master). This version is at an early development stage and we welcome feedback, input and contributions. This version does not currently have feature parity with the Angular 1 version specified below - see the [Development Roadmap](docs/roadmap.md) for more information. + Stratos provides the feature set outline below. Some of these are illustrated in the [Screenshots gallery](images/screenshots/README.md). * Authentication diff --git a/docs/i18n.md b/docs/i18n.md index 3f7bb092d4..0fc6e721e9 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -1,92 +1,3 @@ # Internationalization (i18n) -Stratos supports i18n via Angular's [$translate service](https://github.com/angular-translate/angular-translate). Dates and times are handled by [Moment](https://momentjs.com/)'s i18n process. -The locale shown will at first be selected from the browser. Any change of locale by the user will be retained within the browser's session. - -The source for all translations can be found in the relevant component's i18n folder. For example: - -``` -|-- i18n -| |-- en_US -``` - -or - -``` -|-- frontend -| |-- i18n -| |-- en_US -``` - -Within each locale will be one or more json files. All json files within a locale will be combined and served as i18n/locale-`locale name`.json, for example locale-en_US.json. - -## Supported Locales -The Stratos UI Console is currently provided with a single locale - US English (en-US). Other locales can easily be added as needed. - -## Localization (i10n) -To add a new locale run through the following steps. - -1. Copy the i18n/en_US directory in every plugin and rename it for the required locale. For instance here en_GB is added -``` -|-- frontend -| |-- i18n -| |-- en_US -| |-- en_GB -``` -2. Add the new locale to the selection of locales to choose. For example -* Open the file `components/app-core/frontend/i18n/en_US/locales.json` -* Add the new locale -``` -{ - "locales": { - "locales": "en_US,fr,en_GB", - "en_US": "English (US)", - "en_GB": "English (UK)" - } -} -``` -* Repeat for all versions of the 'locales' object in all other locale files. - -3. Start the stratos ui and the new locale should be visible in the change language drop down. -4. Go through all the new locale's json files and update with the required translations. - -## i10n Useful Information -* To find a string in HTML/JS flatten the property path. For example -``` -{ - "login": { - "timeout": { - "prompt": "Are you still there?" - } - } -} -``` -Becomes -``` -login.timeout.prompt -``` -* If any string is missing it's translation it will appear as a warning in the browser's console output -* Some strings use substitution. For example consider the following -``` -{ - "login": { - "login": "Login", - "console": "@:product.console", - "title": "[[@:product.name]] [[@:product.version]]", - "welcome": "Use the [[@:product.console]] to develop, compose, and manage Cloud Native workloads.", - } -} -``` -login.console will be replaced with the entry for product.console. If a string contains more than the direct replacement then the [[@:]] notation should be used. -* Some strings can contain dynamic content. For exammple -``` -{ - "login": { - "timeout": { - "notice": "You have been inactive for a while. For your protection, we will automatically log you out in {{timeout}}", - } - } -} -``` -login.timeout.notice contains a countdown in seconds until the user is automatically logged out '{{timeout}}'. The text within the curly brackets should not be changed but it's location within the string is for the translator to decide - \ No newline at end of file +WIP