Skip to content

Commit 1122b73

Browse files
priteaupriteau
committed
Document how to customise Horizon
1 parent c63cf4b commit 1122b73

File tree

3 files changed

+169
-0
lines changed

3 files changed

+169
-0
lines changed

‎source/customising_deployment.rst‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
.. include:: vars.rst
2+
3+
====================================
4+
Customising the OpenStack Deployment
5+
====================================
6+
7+
Horizon customisations
8+
======================
9+
10+
Horizon is the most frequent site-specific container customisation required:
11+
other customisations tend to be common across deployments, but personalisation
12+
of Horizon is unique to each institution.
13+
14+
This describes a simple process for customising the Horizon theme.
15+
16+
Creating a custom Horizon theme
17+
-------------------------------
18+
19+
A simple custom theme for Horizon can be implemented as small modifications of
20+
an existing theme, such as the `Default
21+
<https://opendev.org/openstack/horizon/src/branch/master/openstack_dashboard/themes/default>`__
22+
one.
23+
24+
A theme contains at least two files: ``static/_styles.scss``, which can be empty, and
25+
``static/_variables.scss``, which can reference another theme like this:
26+
27+
.. code-block:: scss
28+
29+
@import "/themes/default/variables";
30+
@import "/themes/default/styles";
31+
32+
Some resources such as logos can be overridden by dropping SVG image files into
33+
``static/img`` (since the Ocata release, files must be SVG instead of PNG). See
34+
`the Horizon documentation
35+
<https://docs.openstack.org/horizon/latest/configuration/themes.html#customizing-the-logo>`__
36+
for more details.
37+
38+
Content on some pages such as the splash (login) screen can be updated using
39+
templates.
40+
41+
See `our example horizon-theme <https://github.com/stackhpc/horizon-theme>`__
42+
which inherits from the default theme and includes:
43+
44+
* a custom splash screen logo
45+
* a custom top-left logo
46+
* a custom message on the splash screen
47+
48+
Further reading:
49+
50+
* https://docs.openstack.org/horizon/latest/configuration/customizing.html
51+
* https://docs.openstack.org/horizon/latest/configuration/themes.html
52+
* https://docs.openstack.org/horizon/latest/configuration/branding.html
53+
54+
Building a custom Horizon container image
55+
-----------------------------------------
56+
57+
Building a custom container image for Horizon can be done by modifying
58+
``kolla.yml`` to fetch the custom theme and include it in the image:
59+
60+
.. code-block:: console
61+
:substitutions:
62+
63+
kolla_sources:
64+
horizon-additions-theme-|horizon_theme_name|:
65+
type: "git"
66+
location: |horizon_theme_clone_url|
67+
reference: master
68+
69+
kolla_build_blocks:
70+
horizon_footer: |
71+
# Binary images cannot use the additions mechanism.
72+
{% raw %}
73+
{% if install_type == 'source' %}
74+
ADD additions-archive /
75+
RUN mkdir -p /etc/openstack-dashboard/themes/|horizon_theme_name| \
76+
&& cp -R /additions/horizon-additions-theme-|horizon_theme_name|-archive-master/* /etc/openstack-dashboard/themes/|horizon_theme_name|/ \
77+
&& chown -R horizon: /etc/openstack-dashboard/themes
78+
{% endif %}
79+
{% endraw %}
80+
81+
If using Train on CentOS 8, don’t forget to set:
82+
83+
.. code-block:: console
84+
85+
kolla_tag: train-centos8
86+
87+
Build the image with:
88+
89+
.. code-block:: console
90+
91+
kayobe overcloud container image build horizon -e kolla_install_type=source --push
92+
93+
Pull the new Horizon container to the controller:
94+
95+
.. code-block:: console
96+
97+
kayobe overcloud container image pull --kolla-tags horizon
98+
99+
Deploy and use the custom theme
100+
-------------------------------
101+
102+
Switch to source image type in ``${KAYOBE_CONFIG_PATH}/kolla/globals.yml``:
103+
104+
.. code-block:: console
105+
106+
horizon_install_type: source
107+
108+
Configure Horizon to include the custom theme and use it by default:
109+
110+
.. code-block:: console
111+
112+
mkdir -p ${KAYOBE_CONFIG_PATH}/kolla/config/horizon/
113+
114+
Add to ``${KAYOBE_CONFIG_PATH}/kolla/config/horizon/custom_local_settings``:
115+
116+
.. code-block:: console
117+
:substitutions:
118+
119+
AVAILABLE_THEMES = [
120+
('default', 'Default', 'themes/default'),
121+
('material', 'Material', 'themes/material'),
122+
('|horizon_theme_name|', '|project_name|', '/etc/openstack-dashboard/themes/|horizon_theme_name|'),
123+
]
124+
DEFAULT_THEME = '|horizon_theme_name|'
125+
126+
You can also set other customisations in this file, such as the HTML title of the page:
127+
128+
.. code-block:: console
129+
:substitutions:
130+
131+
SITE_BRANDING = "|project_name| OpenStack"
132+
133+
Deploy with:
134+
135+
.. code-block:: console
136+
137+
kayobe overcloud service reconfigure --kolla-tags horizon --kolla-skip-tags common --skip-prechecks
138+
139+
Troubleshooting
140+
---------------
141+
142+
Make sure you build source images, as binary images cannot use the addition
143+
mechanism used here.
144+
145+
If the theme is selected but the logo doesn’t load, try running these commands
146+
inside the ``horizon`` container:
147+
148+
.. code-block:: console
149+
150+
/var/lib/kolla/venv/bin/python /var/lib/kolla/venv/bin/manage.py collectstatic --noinput --clear
151+
/var/lib/kolla/venv/bin/python /var/lib/kolla/venv/bin/manage.py compress --force
152+
settings_bundle | md5sum > /var/lib/kolla/.settings.md5sum.txt
153+
154+
Alternatively, try changing anything in ``custom_local_settings`` and restarting
155+
the ``horizon`` container.
156+
157+
If the ``horizon`` container is restarting with the following error:
158+
159+
.. code-block:: console
160+
161+
/var/lib/kolla/venv/bin/python /var/lib/kolla/venv/bin/manage.py compress --force
162+
CommandError: An error occurred during rendering /var/lib/kolla/venv/lib/python3.6/site-packages/openstack_dashboard/templates/horizon/_scripts.html: Couldn't find any precompiler in COMPRESS_PRECOMPILERS setting for mimetype '\'text/javascript\''.
163+
164+
It can be resolved by dropping cached content with ``docker restart
165+
memcached``. Note this will log out users from Horizon, as Django sessions are
166+
stored in Memcached.

‎source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Contents
2424
ceph_storage
2525
managing_users_and_projects
2626
operations_and_monitoring
27+
customising_deployment
2728

2829
Indices and search
2930
==================

‎source/vars.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
.. |floating_ip_access| replace:: from acme-seed-hypervisor and the rest of the Acme network
1010
.. |grafana_url| replace:: https://openstack.acme.example:3000
1111
.. |horizon_access| replace:: via the Internet.
12+
.. |horizon_theme_clone_url| replace:: https://github.com/acme-openstack/horizon-theme.git
13+
.. |horizon_theme_name| replace:: acme
1214
.. |horizon_url| replace:: https://openstack.acme.example
1315
.. |hypervisor_hostname| replace:: ``comp0``
1416
.. |hypervisor_type| replace:: KVM

0 commit comments

Comments
 (0)