Verrazzano Console

You can use the Verrazzano Console to access and manage Verrazzano components and applications deployed to a Verrazzano environment.

The Verrazzano Console repository includes:

• hooks: The Oracle JavaScript Extension Toolkit (JET) hooks used for building and running the Console application.
• jet-composites: The Oracle JET Custom Components which are basic building blocks for the Console.
• views and viewModels: The Oracle JET Views and ViewModels used in the Console. See Oracle JET Architecture for more details.
• test: The tests and test-related configuration for the Console.

Prerequisites

• Node.js 14.x+ (with npm v6.14.x+)

  To install Node.js, use nvm:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
    nvm install 14.15

• Oracle JET CLI 10.1.x+

  The Verrazzano Console uses the Oracle JET framework. The Oracle JET command-line interface (ojet-cli) is required to run Oracle JET Tooling commands, which you can install with npm.

    npm install -g @oracle/[email protected]

  For more information, see Getting Started with Oracle JavaScript Extension Toolkit (JET).

• An existing Verrazzano environment and access to the Verrazzano API.

  The Verrazzano Console requires the URL of the Verrazzano Auth-Proxy Server (for fetching environment and application data). The format of the Verrazzano Auth-Proxy URL typically is https://verrazzano.v8o-env.v8o-domain.com where:

  • v8o-env is the name of the Verrazzano environment and v8o-domain.com is the domain, when a DNS provider is used.
  • v8o-env is replaced by default and v8o-domain.com is the IP address of load balancer for the Kubernetes cluster, when a "magic" DNS provider like xip.io is used.

  For more details on installing and accessing Verrazzano, see the installation instructions.

Setup

Clone the git repository and install npm dependencies:

  git clone https://github.com/verrazzano/console.git
  cd console
  nvm use 14.15
  npm install

Get Verrazzano user credentials

Verrazzano installations have a default user verrazzano configured in the Verrazzano Keycloak server which can be used for authentication for accessing the Console. To get the password for the verrazzano user from the management cluster, run:

   kubectl get secret --namespace verrazzano-system verrazzano -o jsonpath={.data.password} | base64 --decode; echo

The Verrazzano Console accesses the Verrazzano API using Verrazzano Auth-Proxy. The Auth-Proxy uses Keycloak to authenticate and authorize the user. Post authentication and authorization, two cookies - vz_authn and vz_userinfo, are set in the browser. The vz_authn cookie is used for the subsequent requests by the Verrazzano Console, while vz_userinfo cookie is consumed by the Verrazzano Console to retrieve information relevant to the logged in user.

Set up environment variables

Set the following environment variable:

  export VZ_API_URL=<your Verrazzano API Server URL> e.g. https://verrazzano.default.11.22.33.44.xip.io

Start server

To run the Console application in a local web server, run following command:

  ojet serve

This will open a tab with the Verrazzano API Server URL.

To start using the Console, authenticate using Verrazzano user credentials in the Verrazzano API tab. Post authentication, open the http://localhost:8000 page in the same window (so that the cookies can be used by localhost for API calls) to view the local Console.

After some time, the cookie expires and the Console prompts you to reload. In that case, navigate to the Verrazzano API URL and reauthenticate with the Verrazzano credentials.

When you make changes to the Console code, the changes are reflected immediately in the browser because the livereload option is enabled by default for the ojet serve command. For other options supported by the command, see Serve a Web Application.

Using Google Chrome for development

Newer versions of Google Chrome (>= 91), do not have the support for disabling samesite-by-default-cookies. This is required for testing the Console locally. To disable this feature, start chrome with the following flag:

–disable-features=SameSiteByDefaultCookies

Testing

Unit tests for the Verrazzano Console use Karma and Mocha. For running the tests, you need the Chrome browser. To run tests for the Console, run:

  make unit-test

Integration tests for the Verrazzano Console use Mocha and Selenium. For running the tests, you need the Chrome browser and the chromedriver version appropriate for the version of your Chrome browser.

To run integration tests for the Console:

• Set the environment variable VZ_UITEST_CONFIG to a UI test configuration file (a sample is provided in integtest/config.uitest.json, which you may edit to add login information).
• Run the tests using the following command:

npm run integtest

Alternatively, use the following command to run integration tests with default configuration:

make run-ui-tests

Building

To build the Console, run the following commands:

• Oracle JET build:

  make ojet-build
  

• Docker build:

  make build
  

Linting

ESLint and prettier are used to keep the code style consistent. To run linting locally:

npm run eslint

Check the formatting of your code using prettier:

npm run prettier

To format your code using prettier:

npm run prettier-write

Contributing to Verrazzano

Oracle welcomes contributions to this project from anyone. Contributions may be reporting an issue with Verrazzano or submitting a pull request. Before embarking on significant development that may result in a large pull request, it is recommended that you create an issue and discuss the proposed changes with the existing developers first.

If you want to submit a pull request to fix a bug or enhance an existing feature, please first open an issue and link to that issue when you submit your pull request.

If you have any questions about a possible submission, feel free to open an issue too.

Contributing to the Verrazzano Console repository

Pull requests can be made under The Oracle Contributor Agreement (OCA), which is available at https://www.oracle.com/technetwork/community/oca-486395.html.

For pull requests to be accepted, the bottom of the commit message must have the following line, using the contributor’s name and e-mail address as it appears in the OCA Signatories list.

Signed-off-by: Your Name <[email protected]>

This can be automatically added to pull requests by committing with:

git commit --signoff

Only pull requests from committers that can be verified as having signed the OCA can be accepted.

Pull request process

• Fork the repository.
• Create a branch in your fork to implement the changes. We recommend using the issue number as part of your branch name, for example, 1234-fixes.
• Ensure that any documentation is updated with the changes that are required by your fix.
• Ensure that any samples are updated if the base image has been changed.
• Submit the pull request. Do not leave the pull request blank. Explain exactly what your changes are meant to do and provide simple steps on how to validate your changes. Ensure that you reference the issue you created as well. We will assign the pull request to 2-3 people for review before it is merged.

Introducing a new dependency

Please be aware that pull requests that seek to introduce a new dependency will be subject to additional review. In general, contributors should avoid dependencies with incompatible licenses, and should try to use recent versions of dependencies. Standard security vulnerability checklists will be consulted before accepting a new dependency. Dependencies on closed-source code, including Oracle's, will most likely be rejected.

Dependencies that satisfy all those constraints, can be added by:

• Installing the dependency using npm i <dep@version> --save
• Editing the src/js/path_mapping.json file to tell JET to bundle the library with the application. Instructions for Oracle JET 9 are here: https://docs.oracle.com/en/middleware/developer-tools/jet/9/develop/add-third-party-tools-or-libraries-your-oracle-jet-application.html.

Useful links

• Oracle JET Cookbook
• VComponent API Documentation
• Overview of Web Components

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Security

Please consult the security guide for our responsible security vulnerability disclosure process

License

The correct copyright notice format for both documentation and software is "Copyright (c) [year,] year Oracle and/or its affiliates." You must include the year the content was first released (on any platform) and the most recent year in which it was revised

Copyright (c) 2023 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.