Create custom Dashboard themes

Create custom Dashboard themes to align the web interface with your organization’s branding, visual identity, and user experience requirements.

Prerequisites
Copy link

  • Administrative privileges for the RHOSO environment
  • Experience using the Linux file system and commands

Dashboard theme elements
Copy link

Dashboard themes control visual elements including logos, colors, stylesheets, and branding to provide a consistent user experience aligned with your organization’s identity.

By default, the Red Hat OpenStack Services on OpenShift (RHOSO) Dashboard (horizon) uses the RCUE theme. You can create your own theme to customize the following Dashboard elements:

  • Logo
  • Site colors
  • Stylesheets
  • HTML title
  • Site branding link
  • Help URL

Theming workflow
Copy link

The theming workflow guides you from downloading the base RCUE theme through customization and deployment to your control plane.

  1. Download the openstack-dashboard-theme Red Hat package that contains the RCUE theme.
  2. Copy this openstack-dashboard-theme Red Hat package to your RHOSO deployment environment and extract it.
  3. Create your theme by customizing the necessary files to change the Dashboard elements that you require.
  4. Create a configuration file for your theme to replace the default RCUE theme and further customize the appearance of your theme.
  5. Add your Dashboard theme to the RHOSO control plane.
Important

If you update or upgrade your RHOSO, then you must reapply your Dashboard theme.

Download the Dashboard theme package
Copy link

Download the openstack-dashboard-theme package from the Customer Portal to use as the foundation for creating a custom Dashboard theme.

Procedure
Copy link

  1. Open the Red Hat Package Browser.
  2. Search for openstack-dashboard-theme package.

    If more than one openstack-dashboard-theme package is listed in the Package column of the search results, then select the Red Hat OpenStack Services on OpenShift product from the Browse packages for all of my listed products list that is adjacent to the search box to refine the search results.

  3. Click the NOARCH in the Architectures column of the search results to display the openstack-dashboard-theme page.
  4. Download the latest Version of this package. The latest version is automatically selected for you.
  5. Check that the Product (Variant, Version, Architecture) column specifies Red Hat OpenStack Services on OpenShift 18.0 x86_64.
  6. Click the Download Now button for the Package download, for example, Package - openstack-dashboard-theme-23.0.2-0.el9ost.noarch.rpm.
    Note
    If you download the Source Package file instead, then you must extract the files from this tar archive file before continuing.

Extract the base theme files
Copy link

Copy the openstack-dashboard-theme package to your deployment environment and extract the RCUE theme files to use as the base for your custom theme.

Procedure
Copy link

  1. Copy the downloaded openstack-dashboard-theme RPM file to a directory for the Dashboard themes in your RHOSO deployment environment: 
    $ rsync -avz <package_download_path> <user>@<deployment_host>:<deployment_themes_path>

    where:

    <package_download_path>
    Specifies the local path of the Openstack Dashboard theme package that you downloaded, for example, /home/Downloads/openstack-dashboard-theme-23.0.2-0.el9ost.noarch.rpm.
    <user>@<deployment_host>
    Specifies the remote user and address of your deployment server, for example, root@lenovo-15.
    <deployment_themes_path>
    Specifies the path of directory for the Dashboard themes on your deployment server, for example, ~/horizon-themes/.
  2. Extract the files and directories of the RCUE theme: 
    $ cd <deployment_themes_path>
$ rpm2cpio <theme_rpm_name> | cpio -idmv

    where:

    <deployment_themes_path>
    Specifies the path of directory you created to store your Dashboard themes on your deployment server, for example, ~/horizon-themes/.
    <theme_rpm_name>
    Specifies the name of your RPM file, for example, openstack-dashboard-theme-23.0.2-0.el9ost.noarch.rpm.

Build your custom Dashboard theme
Copy link

Create your custom theme by copying the RCUE theme directory, customizing visual elements, and packaging the modified files as a tarball for deployment.

Procedure
Copy link

  1. Copy the extracted usr directory of the RCUE theme in your RHOSO deployment to a new subdirectory, for example, mytheme: 
    $ cp -r <rcue_themes_usr_directory_path> <your_dashboard_theme_path>

    where:

    <rcue_themes_usr_directory_path>
    Specifies the path in your RHOSO deployment of the usr directory of the RCUE theme, for example, ~/horizon-themes/usr/share/openstack-dashboard/openstack_dashboard/themes/rcue/.
    <your_dashboard_theme_path>
    Specifies the path of your Dashboard theme, for example, ~/horizon-themes/mytheme.
  2. Replace all the instances of rcue in your Dashboard theme directory, for example ~/horizon-themes/mytheme, with the name of your Dashboard theme, for example, mytheme. You must include the paths, files, and subdirectories.

    The following command highlights all the instances of rcue that you must replace in your Dashboard theme directory:

    $ grep -r 'rcue'
  3. Edit the required files in your Dashboard theme directory to change the colors, graphics, fonts, and other elements of your theme.
  4. Navigate to the Dashboard themes directory on your deployment server: 
    $ cd <dashboard_themes_path>

    where:

    <dashboard_themes_path>
    Specifies the path of the Dashboard (horizon) themes directory, for example, ~/horizon-themes/.
  5. Create a tarball of your theme directory:
    Note
    Only the tar.gz format is supported.
     
    $ tar -cvzf <your_dashboard_theme_name>.tar.gz <your_dashboard_theme_path>

    where:

    <your_dashboard_theme_name>
    Specifies the name of your Dashboard theme, for example, mytheme.
    <your_dashboard_theme_path>
    Specifies the path in your RHOSO deployment of your Dashboard theme, for example, ~/horizon-themes/mytheme/.

Create your Dashboard theme configuration file
Copy link

Create a configuration file to activate your custom theme and define additional appearance settings such as site branding and navigation links.

Procedure
Copy link

  1. Open the Dashboard themes directory on your deployment server: 
    $ cd <dashboard_themes_path>

    where:

    <dashboard_themes_path>
    Specifies the path of the Dashboard themes directory on your deployment server, for example, ~/horizon-themes/.
  2. Use your preferred text editor to create a new configuration file called 12<theme_name>_theme.py.

    where:

    <theme_name>
    Specifies the name of your theme, for example, mytheme.
    Note
    The prefix of this file must have a number greater than 11. This ensures that your theme configuration file is loaded after the default RCUE theme configuration file to override its settings.
  3. Edit this file to specify the following mandatory parameter: 
    AVAILABLE_THEMES = [('<theme_name>', '<theme_description>', 'themes/<theme_name>')]

    where:

    <theme_name>
    Specifies the name of your theme, for example, mytheme.
    <theme_description>
    Specifies a brief description of your theme, for example, My theme.
    Important
    When you specify the third argument of the AVAILABLE_THEMES parameter, the parent directory must always be themes, for example, themes/mytheme.
  4. Optional: You can specify the following parameters to further customize the appearance of your theme:
    • SITE_BRANDING: Provide the HTML title that is displayed at the top of the browser window. For example, SITE_BRANDING = "Example, Inc. Cloud".
    • SITE_BRANDING_LINK : Provide the hyperlink of the theme logo, which redirects to horizon:user_home, by default. For example, SITE_BRANDING_LINK = "http://example.com".

Apply your custom theme to the control plane
Copy link

Apply your custom theme to the Dashboard by creating a ConfigMap and updating the OpenStackControlPlane custom resource to mount the theme files in the horizon service pod.

Procedure
Copy link

  1. Create the ConfigMap file called horizon-theme that specifies the location in your RHOSO deployment of the tarball and the configuration file that you have created for your theme: 
    $ oc create cm horizon-theme \
--from-file=<your_theme_tarball_path> \
--from-file=<your_theme_configuration_file_path>

    where:

    <your_theme_tarball_path>
    Specifies the location in your RHOSO deployment of the archive containing your theme files, for example, $HOME/horizon-themes/mytheme.tar.gz.
    <your_theme_configuration_file_path>
    Specifies the location in your RHOSO deployment of the configuration file of your theme, for example, $HOME/horizon-themes/_12_mytheme_theme.py.
  2. Open your OpenStackControlPlane CR file, openstack_control_plane.yaml, on your workstation.
  3. Add the .spec.horizon.template.extramounts section: 
    kind: OpenStackControlPlane
spec:
  ...
  horizon:
    enabled: true
    template:
      extraMounts:
      - extraVol:
        - extraVolType: HorizonTheme
          mounts:
          - mountPath: /etc/openstack-dashboard/local_settings.d/<your_theme_configuration_filename>
            name: horizon-theme
            readOnly: true
            subPath: <your_theme_configuration_filename>
          - mountPath: /etc/openstack-dashboard/theme/<your_theme_tarball>
            name: horizon-theme
            readOnly: true
            subPath: <your_theme_archive>
          volumes:
          - configMap:
              name: horizon-theme
            name: horizon-theme
  ...

    where:

    <your_theme_configuration_filename>
    Specifies the file name and extension of your Dashboard theme configuration file, for example, _12_mytheme_theme.py.
    <your_theme_tarball>
    Specifies the file name and extension of the archive you created to contain your Dashboard theme files, for example, mytheme.tar.gz.
  4. Apply the changes made to the OpenStackControlPlane CR file: 
    $ oc apply -f openstack_control_plane.yaml -n openstack
  5. Wait for the new horizon service pod to be deployed by running the following command and waiting for the Message field to display Setup complete: 
    $ oc get horizon -w
NAME      NETWORKATTACHMENTS   STATUS   MESSAGE
horizon                        True     Setup complete

    The RHOSO Dashboard uses your theme.