Skip to content

Latest commit

 

History

History
764 lines (633 loc) · 23.9 KB

web_console_customization.adoc

File metadata and controls

764 lines (633 loc) · 23.9 KB

Customizing the Web Console

Configuring Catalog Categories

Catalog categories organize the display of builder images and templates on the Add to Project page on the {product-title} web console. A builder image or template is grouped in a category if it includes a tag with the same name of the category or category alias. Categories only display if one or more builder images or templates with matching tags are present in the catalog.

Note

Significant customizations to the catalog categories may affect the user experience and should be done with careful consideration. You may need to update this customization in future upgrades if you modify existing category items.

  1. Create the following configuration scripts within a file (for example, catalog-categories.js):

    // Add Go to the Languages category
var category = _.find(window.OPENSHIFT_CONSTANTS.CATALOG_CATEGORIES,
{ id: 'languages' });
category.items.splice(2,0,{ // Insert at the third spot
  // Required.  Must be unique
  id: "go",
  // Required
  label: "Go",
  // Optional.  If specified, defines a unique icon for this item
  iconClass: "font-icon icon-go-gopher",
  // Optional.  If specified, enables matching other tag values to this category
  // item
  categoryAliases: [
    "golang"
  ]
});

// Add a Featured category section at the top of the catalog
window.OPENSHIFT_CONSTANTS.CATALOG_CATEGORIES.unshift({
  // Required.  Must be unique
  id: "featured",
  // Required
  label: "Featured",
  // Optional.  If specified, each item in the category will utilize this icon
  // as a default
  iconClassDefault: "fa fa-code",
  items: [
    {
      // Required.  Must be unique
      id: "go",
      // Required
      label: "Go",
      // Optional.  If specified, defines a unique icon for this item
      iconClass: "font-icon icon-go-gopher",
      // Optional.  If specified, enables matching other tag values to this
      // category item
      categoryAliases: [
        "golang"
      ],
      // Optional.  If specified, will display below the item label
      description: "An open source programming language developed at Google in
      2007 by Robert Griesemer, Rob Pike, and Ken Thompson."
    },
    {
      // Required.  Must be unique
      id: "jenkins",
      // Required
      label: "Jenkins",
      // Optional.  If specified, defines a unique icon for this item
      iconClass: "font-icon icon-jenkins",
      // Optional.  If specified, will display below the item label
      description: "An open source continuous integration tool written in Java."
    }
  ]
});

  2. Save the file and add it to the master configuration at /etc/origin/master/master-config.yml:

    assetConfig:
  ...
  extensionScripts:
    - /path/to/catalog-categories.js

  3. Restart the master host:

    

    

    

    4. 









Enabling Wildcard Routes




If you enabled wildcard routes for a router, you can also enable wildcard
routes in the web console. This lets users enter hostnames starting with an
asterisk like *.example.com when creating a route. To enable wildcard routes:






    

  1. 

    Save this script to a file (for example, enable-wildcard-routes.js):
    

    

    

    window.OPENSHIFT_CONSTANTS.DISABLE_WILDCARD_ROUTES = false;
    

    

    

    2. 

  2. 

    Add it to the master configuration file:
    

    

    

    assetConfig:
  ...
  extensionScripts:
    - /path/to/enable-wildcard-routes.js
    

    

    

    3. 










Enabling Features in Technology Preview




Sometimes features are available in Technology Preview. By default, these
features are disabled in the web console and hidden from end users.






Web console features currently in Technology Preview include:













Feature Name
Description
Script Value







Pipelines


Enabling this feature will add the Pipelines navigation item underneath
 the Builds menu.


pipelines









To enable a Technology Preview feature:






    

  1. 

    Save this script to a file (for example, tech-preview.js):
    

    

    

    window.OPENSHIFT_CONSTANTS.ENABLE_TECH_PREVIEW_FEATURE.<feature_name> = true;
    

    

    

    2. 

  2. 

    Add it to the master configuration file:
    

    

    

    assetConfig:
  ...
  extensionScripts:
    - /path/to/tech-preview.js
    

    

    

    3. 









Serving Static Files






You can serve other files from the Asset Server as well. For example, you might
want to make the CLI executable available for download from the web console or
add images to use in a custom stylesheet.






Add the directory with the files you want using the following configuration
option:








assetConfig:
  ...
  extensions:
    - name: images
      sourceDirectory: /path/to/my_images








The files under the /path/to/my_images directory will be available under the
URL /<context>/extensions/images in the web console.






To reference these files from a stylesheet, you should generally use a relative
path. For example:








#header-logo {
  background-image: url("../extensions/images/my-logo.png");
}








Enabling HTML5 Mode




The web console has a special mode for supporting certain static web
applications that use the HTML5 history API:








assetConfig:
  ...
  extensions:
    - name: my_extension
      sourceDirectory: /path/to/myExtension
      html5Mode: true








Setting html5Mode to true enables two behaviors:






    

  1. 

    Any request for a non-existent file under
/<context>/extensions/my_extension/ instead serves
/path/to/myExtension/index.html rather than a "404 Not Found" page.
    

    2. 

  2. 

    The element <base href="/"> will be rewritten in
/path/to/myExtension/index.html to use the actual base depending on the
asset configuration; only this exact string is rewritten.
    

    3. 







This is needed for JavaScript frameworks such as AngularJS that require base
to be set in index.html.












Customizing the Login Page






You can also change the login page, and the login provider selection page for
the web console. Run the following commands to create templates you can modify:








$ oadm create-login-template > login-template.html
$ oadm create-provider-selection-template > provider-selection-template.html








Edit the file to change the styles or add content, but be careful not to remove
any required parameters inside the curly brackets.






To use your custom login page or provider selection page, set the following
options in the master configuration file:








oauthConfig:
  ...
  templates:
    login: /path/to/login-template.html
    providerSelection: /path/to/provider-selection-template.html








Relative paths are resolved relative to the master configuration file. You must
restart the server after changing this configuration.






When there are multiple login providers configured or when the
alwaysShowProviderSelection
option in the master-config.yaml file is set to true, each time a user’s
token to {product-title} expires, the user is presented with this custom page
before they can proceed with other tasks.






Example Usage




Custom login pages can be used to create Terms of Service information. They can
also be helpful if you use a third-party login provider, like GitHub or Google,
to show users a branded page that they trust and expect before being redirected
to the authentication provider.












Customizing the OAuth Error Page






When errors occur during authentication, you can change the page shown.






    

  1. 

    Run the following command to create a template you can modify:
    

    

    

    $ oadm create-error-template > error-template.html
    

    

    

    2. 

  2. 

    Edit the file to change the styles or add content.
    

    

    You can use the Error and ErrorCode variables in the template. To use
your custom error page, set the following option in the master configuration
file:
    

    

    

    

    oauthConfig:
  ...
  templates:
    error: /path/to/error-template.html
    

    

    

    

    Relative paths are resolved relative to the master configuration file.
    

    

    3. 

  3. 

    You must restart the server after changing this configuration.
    

    4. 











Changing the Logout URL






You can change the location a console user is sent to when logging out of
the console by modifying the logoutURL parameter in the
/etc/origin/master/master-config.yaml file:








...
assetConfig:
  logoutURL: "http://www.example.com"
...








This can be useful when authenticating with
Request
Header and OAuth or
OpenID identity
providers, which require visiting an external URL to destroy single sign-on
sessions.










Configuring Web Console Customizations with Ansible






During
advanced installations,
many modifications to the web console can be configured using
the following parameters, which are configurable in the inventory file:







Example Web Console Customization with Ansible




# Configure logoutURL in the master config for console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#changing-the-logout-url
#openshift_master_logout_url=http://example.com

# Configure extensionScripts in the master config for console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#loading-custom-scripts-and-stylesheets
#openshift_master_extension_scripts=['/path/on/host/to/script1.js','/path/on/host/to/script2.js']

# Configure extensionStylesheets in the master config for console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#loading-custom-scripts-and-stylesheets
#openshift_master_extension_stylesheets=['/path/on/host/to/stylesheet1.css','/path/on/host/to/stylesheet2.css']

# Configure extensions in the master config for console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#serving-static-files
#openshift_master_extensions=[{'name': 'images', 'sourceDirectory': '/path/to/my_images'}]

# Configure extensions in the master config for console customization
# See: https://docs.openshift.com/enterprise/latest/install_config/web_console_customization.html#serving-static-files
#openshift_master_oauth_template=/path/on/host/to/login-template.html

# Configure metricsPublicURL in the master config for cluster metrics. Ansible is also able to configure metrics for you.
# See: https://docs.openshift.com/enterprise/latest/install_config/cluster_metrics.html
#openshift_master_metrics_public_url=https://hawkular-metrics.example.com/hawkular/metrics

# Configure loggingPublicURL in the master config for aggregate logging. Ansible is also able to install logging for you.
# See: https://docs.openshift.com/enterprise/latest/install_config/aggregate_logging.html
#openshift_master_logging_public_url=https://kibana.example.com