Theming The OpenStack Dashboard In Kilo

Horizon, the OpenStack Dashboard, included an incredibly powerful new feature in the Kilo release (May 2015). This feature is the ability to theme the user interface. While the feature is still in its infant form it provides an incredible amount of flexibility in altering the branding and overall feel.

By Example

In local_settings.py, the settings file for Horizon, you can specify a custom theme by setting the CUSTOM_THEME_PATH. The path sets a directory for a theme to use. The path is either relative to the openstack_dashboard directory or absolute to a path on the file system.

A theme consists of the two files _variables.scss and _styles.scss.

The variables files allows you to alter the Bootstrap or other Horizon SCSS variables. For example, you can set the $btn-default-color to a different color and all the buttons using the default color will change.

The styles file is the final SCSS file loaded by Horizon. It enables you to add any SCSS of your own. Because of cascading rules you can override any existing styles. This is an additive method to overrides.

Note, if you're going to make a lot of changes to Horizon you may want to have multiple SCSS files in your theme and leverage @import to pull them into the styles file. This can make it easier to maintain.

For more information on theming see the Theming section of the customization guide.

Some Limitations

Theming landed as one of the last features into the Kilo release. What landed had a number of limitations that are worth knowing about.

  • The favicon is hard coded in a template file. You'll need to use a little template overriding magic or forking to change it.
  • Template overriding, while possible through some settings magic, isn't coupled to the theme system.
  • Some bugs exist in the default status of built-in style variables.