Create a Custom Horizon Branding Tarball¶

This section contains instructions and examples for creating and applying a tarball containing a custom Horizon Web interface theme, and associated branding files, for the StarlingX.

You can modify the existing style sheet, font, and image files to develop your own branding, package it, and then apply the branding by installing the tarball that includes the modified files along with a manifest. To create a custom branding tarball, with a new custom theme, and package it, follow the steps below:

Procedure

You can use the existing ‘basic’ Horizon theme as a starting point for the creation of your custom theme or just for the directory structure. This theme can be found on a controller host, at /usr/share/openstack-dashboard/themes/basic/.
Customize the login page logo (logo-splash.png), navbar logo (logo.png) and browser tab icon (favicon.png) by replacing the corresponding files in the static/img/ folder.
Customize the styles and color scheme by updating the _styles.scss, and _variables.scss files.
Template overrides can be placed in the templates folder.
Copy the theme into a writable file system such as /home/$user or /usr/share/openstack-dashboard/themes and modify it to fit your requirements.

‘basic’ theme structure:
```
basic/
├── manifest.py                # Site name and help URL
├── static/
│   ├── _styles.scss           # CSS overrides (logo sizing)
│   ├── _variables.scss        # SCSS variable overrides (colors, fonts, spacing)
│   └── img/
│       ├── logo.png           # Navbar logo (top-left)
│       ├── logo-splash.png    # Login page logo
│       └── favicon.png        # Browser tab icon
└── templates/
    ├── _stylesheets.html      # Overrides favicon path and stylesheets
    ├── header/
    │   └── _brand.html        # Overrides navbar logo path
    └── auth/
        └── _splash.html       # Overrides login logo path
```
Note

Standard for custom images in ‘basic’ theme are .png files named as: logo.png/logo-splash.png/favicon.png. If you want to use .svg (Scalable Vector Graphics) or .ico (Icon File) files, change paths for overrides on the html files provided on ‘basic’ theme.

For more information on customizing your theme, see the OpenStack documentation at, https://docs.openstack.org/horizon/latest/configuration/branding.html
Note
- You can alternatively use ‘basic’ theme as a guide to where customized templates and javascript must be located in a custom theme, and can be found next to the default theme.
- The name of the custom theme can be chosen by the user and must be used in the source paths of new images or javascript, for example, /static/themes/custom/img/extra_img.png.
- If a static folder is used, the _styles.scss, and _variables.scss files must be located in the static folder and not in the root of the theme.
If you use ‘basic’ as a starting point, you only need to modify the manifest.py file as required. Otherwise, you must add a manifest.py file to your theme directory that is used to overwrite Horizon’s branding-related settings. This file should specify the following information:
```
# SITE_BRANDING = "Sample System Name"
```
where
Sample System Name is the name that will be used in the site title
```
# HORIZON_CONFIG["help_url"] = "https://www.openstack.org/"
```
where
the help_url is the help link for users (‘basic’ has this line commented).

Compress this directory into a tarball that can then be deployed in running systems.

Note

This tarball must have the extension .tgz. There are no limitations on the name of this file.

# ls manifest.py static templates

# tar czfv new_branding.tgz *
manifest.py
static/
static/img/
static/img/favicon.png
static/img/logo-splash.png
static/img/logo.png
static/img/logo.png
static/_styles.scss
static/_variables.scss
templates/
templates/auth/
templates/auth/_splash.html
templates/header
templates/header/_brand.html
templates/_stylesheets.html

Postrequisites

After creating your custom branding tarball containing a customized Horizon Web interface theme and associated branding files, you can apply it to both newly installed and running systems.

For more information on applying the tarball to newly installed systems prior to running the bootstrap playbook, see Apply a Custom Horizon Branding Tarball to Newly Installed Systems.

For more information on applying the tarball to running systems, see Apply a Custom Horizon Branding Tarball to Running Systems.