GUI whitelabel runtime system #8942

BryanMLima · 2024-04-18T17:19:21Z

Description

1. Problem description

Currently ACS allows the GUI personalization (color changing, add a personalized logo, and so on); however, those configurations are set for the whole environment, which does not allow Apache CloudStack to have a personalized GUI by domain, account and so on. In a scenario of cloud providers reselling the infrastructure, the current behavior does not allow the operators to personalize the GUI for each use case (reseller, domain, account, and so on).

2. Proposed Changes

This spec introduces the concept of Runtime White Label to the Apache CloudStack GUI, which combines the market concept of White Label and enables it to be configured in runtime and by scope (domain, account, and so on). Briefly, we will introduce APIs to allow the operators to define GUI themes for a set of Internet common names (fixed or wildcard), a set of ACS domain UUIDs (also known as ID for the end-user), and a set of ACS account UUIDs (also known as ID for the end-user). The APIs will receive the CSS and JSON configuration as parameter and will store them into the database. When accessing Apache CloudStack, the UI will retrieve the CSS and JSON configurations according to the access definition and import them into the browser. If there are no themes match, the GUI will fallback to the current environment configuration.

Operations that create/modify/remove the themes will be registered with events in ACS.

2.1. Database model

A table named gui_themes will be created in the cloud schema and will have the following columns:

Name	Type	Nullable	Default	Description
id	bigint(20) unsigned	No	Auto increment	-
uuid	varchar(40)	No	null	-
name	varchar(2048)	No	null	A name to identify the theme.
description	varchar(4096)	Yes	null	A description for the theme.
css	text	Yes	null	The CSS to be retrieved and imported into the GUI when matching the theme access configurations.

Name	Type	Nullable	Default	Description
json_configuration	text	Yes	null	The JSON with the configurations to be retrieved and imported into the GUI when matching the theme access configurations.
common_names	text	Yes	null	A set of Internet common names (fixed or wildcard) separated by comma that can use the theme; e.g.: `*acme.com,acme2.com`.
domain_uuids	text	Yes	null	A set of [ACS] domain IDs separated by comma that can use the theme.
account_uuids	text	Yes	null	A set of [ACS] account IDs separated by comma that can use the theme
is_public	boolean	Yes	true	Defines whether a theme can be retrieved by anyone when only the `common_names` is informed. If the `domain_uuids` or `account_uuids` is informed, it is considered as `false`.
created	datetime	No	null	When the theme was created.
removed	datetime	Yes	null	When the theme was removed.

2.2. APIs

Right below there are the descriptions of the APIs to be introduced to allow the management of GUI themes by scope.

2.2.1. createGuiTheme

The API createGuiTheme will be accessible only by the operators (Root Admin accounts) and will allow them to create themes for several scopes. It will have the following parameters:

Parameter	Description	Mandatory	Type	Default value	Length
name	A name to identify the theme.	Yes	String	null	2048
description	A description for the theme.	No	String	null	4096

Parameter	Description	Mandatory	Type	Default value	Length
css	The CSS to be retrieved and imported into the GUI when matching the theme access configurations.	No	String	null	65535
jsonconfiguration	The JSON with the configurations to be retrieved and imported into the GUI when matching the theme access configurations. More details about the JSON configurations can be found in the JSON Configurations session.	No	String	null	65535
commonnames	A set of Internet common names (fixed or wildcard) separated by comma that can retrieve the theme; e.g.: `*acme.com,acme2.com`	No	String	null	65535
domainids	A set of [ACS] domain UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme.	No	String	null	65535
accountids	A set of [ACS] account UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme	No	String	null	65535
ispublic	Defines whether a theme can be retrieved by anyone when only the `domainnames` is informed. If the `domainids` or `accountids` is informed, it is considered as `false`.	No	Boolean	true	-

Either css or jsonconfiguration parameter must be informed for the GUI theme creation. If neither commonnames, domainids, and accountids is defined, the theme will be considered as the default; there can exist only one default theme and it automatically will be public. If there are no themes match, the GUI will fallback to the current environment configuration.

2.2.2. listGuiThemes

The API listGuiThemes will be accessible by anyone and will retrieve the themes according to the parameters and the caller access. It will have the following parameters:

Parameter	Description	Mandatory	Type	Default value	Length
id	The theme ID.	No	String	null	40
name	The name of the theme.	No	String	null	2048
commonname	The Internet common name to be filtered.	No	String	null	256
domainid	The UUID (also known as ID for the end-user) of the domain to be filtered.	No	String	null	40
accountid	The UUID (also known as ID for the end-user) of the account to be filtered.	No	String	null	40
listall	Whether to list all themes.	No	Boolean	false	-
listremoved	Whether to list removed themes.	No	Boolean	false	-
ispublic	Whether to list public themes. By default, it lists them all.	No	Boolean	null	-
listonlydefaulttheme	Whether to list only the default theme. If this parameter is `true`, than all other parameters are ignored.	No	Boolean	false	-

In order to allow the theme to be displayed yet in the login web page, it will be possible to call this API without authentication; however, there will be limitations and all the parameters will be ignored. An unauthenticated call to the API listGuiThemes will retrieve no entry or only a single entry; the single entry will be the default theme or the public, most recently, and active theme that matches the Internet common name requesting the API.

2.2.3. updateGuiTheme

The API updateGuiTheme will be accessible only by the operators (Root Admin accounts) and will allow them to update a theme. It will have the following parameters:

Parameter	Description	Mandatory	Type	Default value	Length
id	The ID of the theme to be updated.	Yes	String	null	40
name	A name to identify the theme.	No	String	null	2048
description	A description for the theme.	No	String	null	4096
css	The CSS to be retrieved and imported into the GUI when matching the theme access configurations.	No	String	null	65535
jsonconfiguration	The JSON with the configurations to be retrieved and imported into the GUI when matching the theme access configurations. More details about the JSON configurations can be found in the JSON Configurations session.	No	String	null	65535
commonnames	A set of Internet common names (fixed or wildcard) separated by comma that can retrieve the theme; e.g.: `*acme.com,acme2.com`	No	String	null	65535
domainids	A set of [ACS] domain UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme.	No	String	null	65535
accountids	A set of [ACS] account UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme	No	String	null	65535
ispublic	Defines whether a theme can be retrieved by anyone when only the `domainnames` is informed. If the `domainids` or `accountids` is informed, it is considered as `false`.	No	Boolean	null	-

By default, all the parameters are null; therefore, to remove one of the parameters, it will be necessary to explicitly pass it as an empty string. If commonnames, domainids, and accountids are passed as empty, the theme will be considered as the default; there can exist only one default theme and it automatically will be public. If there are no themes match, the GUI will fallback to the current environment configuration.

2.2.4. removeGuiTheme

The API removeGuiTheme will be accessible only by the operators (Root Admin accounts) and will allow them to remove a theme. It will have the following parameter:

Parameter	Description	Mandatory	Type	Default value	Length
id	The UUID (also known as ID for the end-user) of the theme to be removed.	Yes	String	null	40

If the default theme is removed and there is no match to a theme access configuration, the GUI will fallback to the current environment configuration.

3.0. Future works

With this proposal, it will be only possible to manage the themes via API; for the future, we plan to add support for the themes management on the GUI. We will extend the feature to comply with projects, identity federation and domains change. Also, we will extend the feature to allow domain admins and users to manage their own themes.

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
build/CI

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Screenshots (if appropriate):

There were two themes added with this PR: Dark theme and Apache Foundation theme. They can be used by anyone using the createGuiTheme API. They serve only to demonstrate the usage of this new feature, as presented in the screenshots below:

Apache theme:

Dark theme:

How Has This Been Tested?

I created multiple themes for specific accounts, domains and common names; they were correctly assigned.

How did you try to break this feature and the system with this change?

DaanHoogland · 2024-04-19T06:45:47Z

interesting

DaanHoogland · 2024-04-19T06:46:00Z

@blueorangutan package

blueorangutan · 2024-04-19T06:48:05Z

@DaanHoogland a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2024-04-19T08:00:53Z

Packaging result [SF]: ✔️ el7 ✔️ el8 ✔️ el9 ✖️ debian ✔️ suse15. SL-JID 9322

DaanHoogland · 2024-04-19T08:13:20Z

@blueorangutan test alma9 kvm-alma9 keepEnv

blueorangutan · 2024-04-19T08:14:03Z

@DaanHoogland a [SL] Trillian-Jenkins test job (alma9 mgmt + kvm-alma9) has been kicked to run smoke tests

blueorangutan · 2024-04-19T23:11:02Z

[SF] Trillian test result (tid-9917)
Environment: kvm-alma9 (x2), Advanced Networking with Mgmt server a9
Total time taken: 51841 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t9917-kvm-alma9.zip
Smoke tests completed. 127 look OK, 2 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_01_events_resource	`Error`	318.04	test_events_resource.py
test_01_events_resource	`Error`	318.05	test_events_resource.py
test_04_deploy_vm_for_other_user_and_test_vm_operations	`Failure`	96.36	test_network_permissions.py
ContextSuite context=TestNetworkPermissions>:teardown	`Error`	1.62	test_network_permissions.py

BryanMLima · 2024-04-22T17:56:29Z

@blueorangutan package

blueorangutan · 2024-04-22T17:58:03Z

@BryanMLima a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2024-04-22T19:15:43Z

Packaging result [SF]: ✔️ el7 ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 9365

DaanHoogland · 2024-04-23T09:51:30Z

@blueorangutan test

blueorangutan · 2024-04-23T09:52:03Z

@DaanHoogland a [SL] Trillian-Jenkins test job (centos7 mgmt + kvm-centos7) has been kicked to run smoke tests

github-actions · 2024-04-23T15:19:25Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

blueorangutan · 2024-04-23T23:29:33Z

[SF] Trillian test result (tid-9967)
Environment: kvm-centos7 (x2), Advanced Networking with Mgmt server 7
Total time taken: 47193 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t9967-kvm-centos7.zip
Smoke tests completed. 127 look OK, 2 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_01_events_resource	`Error`	306.15	test_events_resource.py
test_01_events_resource	`Error`	306.16	test_events_resource.py
test_04_deploy_vm_for_other_user_and_test_vm_operations	`Failure`	92.52	test_network_permissions.py
ContextSuite context=TestNetworkPermissions>:teardown	`Error`	1.50	test_network_permissions.py

DaanHoogland · 2024-04-24T07:19:58Z

nice work @BryanMLima , haven't reviewed all of it, but I like it so far.

codecov-commenter · 2024-04-24T13:19:37Z

Codecov Report

Attention: Patch coverage is 8.84265% with 701 lines in your changes missing coverage. Please review.

Project coverage is 16.56%. Comparing base (8e4fe1c) to head (c5f3efd).
Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
...ache/cloudstack/gui/theme/GuiThemeServiceImpl.java	24.32%	166 Missing and 2 partials ⚠️
...va/org/apache/cloudstack/gui/theme/GuiThemeVO.java	0.00%	80 Missing ⚠️
...ache/cloudstack/api/response/GuiThemeResponse.java	0.00%	75 Missing ⚠️
...oudstack/gui/theme/dao/GuiThemeDetailsDaoImpl.java	0.00%	66 Missing ⚠️
.../cloudstack/gui/theme/dao/GuiThemeJoinDaoImpl.java	1.53%	64 Missing ⚠️
.../api/command/user/gui/theme/UpdateGuiThemeCmd.java	0.00%	46 Missing ⚠️
.../api/command/user/gui/theme/CreateGuiThemeCmd.java	0.00%	43 Missing ⚠️
...rg/apache/cloudstack/gui/theme/GuiThemeJoinVO.java	0.00%	43 Missing ⚠️
...k/api/command/user/gui/theme/ListGuiThemesCmd.java	0.00%	36 Missing ⚠️
...apache/cloudstack/gui/theme/GuiThemeDetailsVO.java	0.00%	32 Missing ⚠️
... and 7 more

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #8942      +/-   ##
============================================
- Coverage     16.57%   16.56%   -0.02%     
- Complexity    13988    14009      +21     
============================================
  Files          5745     5758      +13     
  Lines        510847   511578     +731     
  Branches      62140    62192      +52     
============================================
+ Hits          84696    84755      +59     
- Misses       416677   417350     +673     
+ Partials       9474     9473       -1

Flag	Coverage Δ
uitests	`3.91% <ø> (-0.01%)`	⬇️
unittests	`17.46% <8.84%> (-0.02%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

JoaoJandre

Overall looks great, just a few minor remarks.

server/src/main/java/org/apache/cloudstack/gui/theme/GuiThemeServiceImpl.java

ui/public/css/apache-theme.css

ui/public/css/dark-theme.css

hsato03 · 2025-07-07T16:27:38Z

@blueorangutan package

blueorangutan · 2025-07-07T16:28:04Z

@hsato03 a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2025-07-07T17:57:13Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 14073

JoaoJandre · 2025-07-08T11:04:11Z

@DaanHoogland could we run the CI again?

DaanHoogland · 2025-07-09T12:38:30Z

@blueorangutan test

blueorangutan · 2025-07-09T12:40:03Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2025-07-10T06:20:44Z

[SF] Trillian test result (tid-13738)
Environment: kvm-ol8 (x2), Advanced Networking with Mgmt server ol8
Total time taken: 60524 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t13738-kvm-ol8.zip
Smoke tests completed. 140 look OK, 1 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_01_deployVMInSharedNetwork	`Failure`	331.93	test_network.py

BryanMLima · 2025-07-10T09:45:54Z

@DaanHoogland, the tests do not seem related to this PR. I also cannot access the logs to check the failure. Could you trigger the CI again?

DaanHoogland · 2025-07-13T18:34:00Z

@blueorangutan test

blueorangutan · 2025-07-13T18:36:04Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2025-07-14T10:21:06Z

[SF] Trillian test result (tid-13759)
Environment: kvm-ol8 (x2), Advanced Networking with Mgmt server ol8
Total time taken: 53645 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t13759-kvm-ol8.zip
Smoke tests completed. 141 look OK, 0 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/CreateGuiThemeCmd.java

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/ListGuiThemesCmd.java

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/RemoveGuiThemeCmd.java

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/UpdateGuiThemeCmd.java

DaanHoogland · 2025-07-14T12:26:27Z

@bernardodemarco can you apply @sureshanaparti ‘ s sugestions. we can run one more time if anybody feels the need.

Co-authored-by: Suresh Kumar Anaparti <[email protected]>

bernardodemarco · 2025-07-14T12:47:44Z

@bernardodemarco can you apply @sureshanaparti ‘ s sugestions. we can run one more time if anybody feels the need.

@DaanHoogland, sure, done!

sureshanaparti · 2025-07-14T13:12:07Z

@blueorangutan package

blueorangutan · 2025-07-14T13:14:03Z

@sureshanaparti a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2025-07-14T16:59:38Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 14175

sureshanaparti · 2025-07-15T11:12:40Z

@blueorangutan ui

blueorangutan · 2025-07-15T11:13:04Z

@sureshanaparti a Jenkins job has been kicked to build UI QA env. I'll keep you posted as I make progress.

blueorangutan · 2025-07-15T11:14:16Z

UI build failed: ✖️
(SL-JID-668)

* Add first version * Add guithemedetails join * Update since and remove extra line * Limit information on API response for non admin users * Add base files for preset themes * Add miising license * Revert cookie check * Fix imports * Fix pre-commit * Address log4j2 string to format review and add license to css files * Fix infinite loading * Move event details to service implementation * Move view to a specific view file * Refactoring gui theme classes * Normalize package name * Address Henrique review * Fix create table SQL * Add interface for Dao classes * Remove extra tabs * Address unauthorized call when 2FA is enabled * Remove trailing whitespaces * Apply suggestions from code review Co-authored-by: Suresh Kumar Anaparti <[email protected]> --------- Co-authored-by: Henrique Sato <[email protected]> Co-authored-by: Bernardo De Marco Gonçalves <[email protected]> Co-authored-by: Suresh Kumar Anaparti <[email protected]>

BryanMLima added the component:UI label Apr 18, 2024

BryanMLima added this to the 4.20.0.0 milestone Apr 18, 2024

boring-cyborg bot added component:api component:build component:database component:management-server labels Apr 18, 2024

github-actions bot added the status:has-conflicts label Apr 23, 2024

DaanHoogland added the status:needs-testing label Apr 24, 2024

github-actions bot removed the status:has-conflicts label Apr 24, 2024

BryanMLima requested review from JoaoJandre and hsato03 April 30, 2024 12:49

JoaoJandre reviewed May 6, 2024

View reviewed changes

hsato03 reviewed May 7, 2024

View reviewed changes

ui/public/css/apache-theme.css Show resolved Hide resolved

ui/public/css/dark-theme.css Show resolved Hide resolved

github-actions bot added the status:has-conflicts label May 30, 2024

Remove trailing whitespaces

6374971

winterhazel added status:waiting-for-smoketest-results and removed status:needs-testing labels Jul 8, 2025

sureshanaparti reviewed Jul 14, 2025

View reviewed changes

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/CreateGuiThemeCmd.java Outdated Show resolved Hide resolved

sureshanaparti reviewed Jul 14, 2025

View reviewed changes

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/ListGuiThemesCmd.java Outdated Show resolved Hide resolved

sureshanaparti reviewed Jul 14, 2025

View reviewed changes

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/RemoveGuiThemeCmd.java Outdated Show resolved Hide resolved

sureshanaparti reviewed Jul 14, 2025

View reviewed changes

api/src/main/java/org/apache/cloudstack/api/command/user/gui/theme/UpdateGuiThemeCmd.java Outdated Show resolved Hide resolved

Apply suggestions from code review

c5f3efd

Co-authored-by: Suresh Kumar Anaparti <[email protected]>

sureshanaparti merged commit fb6adac into apache:main Jul 15, 2025
38 of 43 checks passed

github-project-automation bot moved this from In Progress to Done in Apache CloudStack 4.21.0 Jul 15, 2025

GUI whitelabel runtime system #8942

GUI whitelabel runtime system #8942

Uh oh!

Conversation

BryanMLima commented Apr 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

1. Problem description

2. Proposed Changes

2.1. Database model

2.2. APIs

2.2.1. createGuiTheme

2.2.2. listGuiThemes

2.2.3. updateGuiTheme

2.2.4. removeGuiTheme

3.0. Future works

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Screenshots (if appropriate):

How Has This Been Tested?

How did you try to break this feature and the system with this change?

Uh oh!

DaanHoogland commented Apr 19, 2024

Uh oh!

DaanHoogland commented Apr 19, 2024

Uh oh!

blueorangutan commented Apr 19, 2024

Uh oh!

blueorangutan commented Apr 19, 2024

Uh oh!

DaanHoogland commented Apr 19, 2024

Uh oh!

blueorangutan commented Apr 19, 2024

Uh oh!

blueorangutan commented Apr 19, 2024

Uh oh!

BryanMLima commented Apr 22, 2024

Uh oh!

blueorangutan commented Apr 22, 2024

Uh oh!

blueorangutan commented Apr 22, 2024

Uh oh!

DaanHoogland commented Apr 23, 2024

Uh oh!

blueorangutan commented Apr 23, 2024

Uh oh!

github-actions bot commented Apr 23, 2024

Uh oh!

blueorangutan commented Apr 23, 2024

Uh oh!

DaanHoogland commented Apr 24, 2024

Uh oh!

codecov-commenter commented Apr 24, 2024 • edited by codecov bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

JoaoJandre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hsato03 commented Jul 7, 2025

Uh oh!

blueorangutan commented Jul 7, 2025

Uh oh!

blueorangutan commented Jul 7, 2025

Uh oh!

JoaoJandre commented Jul 8, 2025

Uh oh!

DaanHoogland commented Jul 9, 2025

Uh oh!

blueorangutan commented Jul 9, 2025

Uh oh!

blueorangutan commented Jul 10, 2025

BryanMLima commented Apr 18, 2024 •

edited

Loading

codecov-commenter commented Apr 24, 2024 •

edited by codecov bot

Loading