Chapter 22. Customizing the Web Console

Administrators can customize the web console using extensions, which let you run scripts and load custom stylesheets when the web console loads. You can change the look and feel of nearly any aspect of the user interface in this way.

To add scripts and stylesheets, edit the master configuration file. The scripts and stylesheet files must exist on the Asset Server and are added with the following options:

assetConfig:
  ...
  extensionScripts:
    - /path/to/script1.js
    - /path/to/script2.js
    - ...
  extensionStylesheets:
    - /path/to/stylesheet1.css
    - /path/to/stylesheet2.css
    - ...

assetConfig:
  ...
  extensionScripts:
    - /path/to/script1.js
    - /path/to/script2.js
    - ...
  extensionStylesheets:
    - /path/to/stylesheet1.css
    - /path/to/stylesheet2.css
    - ...

Relative paths are resolved relative to the master configuration file. To pick up configuration changes, restart the server.

Custom scripts and stylesheets are read once at server start time. To make developing extensions easier, you can reload scripts and stylesheets on every request by enabling development mode with the following setting:

assetConfig:
  ...
  extensionDevelopment: true

assetConfig:
  ...
  extensionDevelopment: true

When set, the web console reloads any changes to existing extension script or stylesheet files when you refresh the page in your browser. You still must restart the server when adding new extension stylesheets or scripts, however. This setting is only recommended for testing changes and not for production.

The following examples show common ways you can customize the web console.

Customizing the Logo

The following style changes the logo in the web console header:

#header-logo {
  background-image: url("https://www.example.com/images/logo.png");
  width: 160px;
  height: 10px;
}

#header-logo {
  background-image: url("https://www.example.com/images/logo.png");
  width: 160px;
  height: 10px;
}

Replace the example.com URL with a URL to an actual image, and adjust the width and height. The ideal height is 10px.

Save the style to a file, for example logo.css, and add it to the master configuration file:

assetConfig:
  ...
  extensionStylesheets:
    - /path/to/logo.css

assetConfig:
  ...
  extensionStylesheets:
    - /path/to/logo.css

Changing the Header Color

The following style changes the header color to dark blue:

.navbar-header {
  background-color: #2B3856;
}

.navbar-header {
  background-color: #2B3856;
}

Save the style to a file, for example theme.css, and add it to the master configuration file:

assetConfig:
  ...
  extensionStylesheets:
    - /path/to/theme.css

assetConfig:
  ...
  extensionStylesheets:
    - /path/to/theme.css

Adding a Link to the Header

The following script adds a link into the web console header:

$(".navbar-utility").prepend('<li><a href="http://example.com/status/">System Status</a></li>');

$(".navbar-utility").prepend('<li><a href="http://example.com/status/">System Status</a></li>');

Save this script to a file, for example nav-link.js, and add it to the master configuration file:

assetConfig:
  ...
  extensionScripts:
    - /path/to/nav-link.js

assetConfig:
  ...
  extensionScripts:
    - /path/to/nav-link.js

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

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");
}

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

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

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

You can also change the login page for the web console. Run the following command to create a template you can modify:

oadm create-login-template > login-template.html

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

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

To use your custom login page, set the following option in the master configuration file:

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

oauthConfig:
  ...
  templates:
    login: /path/to/login-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 OpenShift Enterprise expires, the user is presented with this custom page before they can proceed with other tasks.

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

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"
...

...
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.