starlingx/docs
Code Issues Proposed changes
b718e9e16d
docs/doc/source/system_configuration/kubernetes/creating-a-custom-branding-tarball.rst
Ron Stone f125a8b892 Remove spurious escapes (r8,dsR8) 
This change addresses a long-standing issue in rST documentation imported from XML.
That import process added backslash escapes in front of various characters. The three
most common being '(', ')', and '_'.
These instances are removed.

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: Id43a9337ffcd505ccbdf072d7b29afdb5d2c997e
2023-03-01 11:19:04 +00:00

4.7 KiB
Raw Blame History

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 .

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:

  1. You can use the existing default Horizon theme as a starting point for the creation of your custom theme or for the directory structure.

  2. Customize the styles and color scheme using the _styles.scss, and _variables.scss files. Image overrides can be placed in the static/img/ folder, and template overrides can be placed in the templates folder. This theme can be found in the Horizon repository, at GitHub or on a controller host, at /usr/share/openstack-dashboard/openstack_dashboard/themes/default/.

  3. Copy the theme and modify it to fit your requirements.

    For more information on customizing your theme, see the OpenStack documentation at, https://docs.openstack.org/horizon/latest/configuration/branding.html

    Note

    • You can use the example 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 is custom 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.

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

    The theme directory should have the following files, depending on how extensive the theme is. Use the following command to find the files:

    # find .
./manifest.py
./static
./static/img
./static/img/logo-splash.svg
./static/img/logo.svg
./static/_styles.scss
./static/_variables.scss
./templates
./templates/auth
./templates/auth/login.html
./templates/auth/_login_form.html
./templates/base.html

  5. 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.svg
static/img/logo.png
static/img/logo.svg
static/_styles.scss
static/_variables.scss
templates/
templates/auth/
templates/auth/login.html
templates/auth/_login_form.html
templates/base.html

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

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 <applying-a-custom-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 <applying-a-custom-branding-tarball-to-running-systems>.