Custom CSS in Jupiter for main cPanel interface - How to add your own stylesheet

[pkiff]

2 minutes ago

I am sharing a (provisional, unapproved) method to add a custom stylesheet to the Jupiter theme used in the main cPanel interface. As of May 2023, cPanel (version 110.0.5 - RELEASE tier) does not provide an official, supported method to do this.

Note:

The Jupiter theme used in the main cPanel interface is different than the Jupiter theme used in the Webmail interface.

This thread is dedicated to:
Custom CSS in Jupiter for main cPanel interface - How to add your own stylesheet

A separate thread is dedicated to:
Custom CSS in Jupiter for Webmail interface - How to add your own stylesheet

Summary:

We add a new LESS partial file to the pre-existing base_overrides LESS and then recompile base_overrides.min.css.
This method requires good familiarity with LESS, CSS preprocessors, and minification.

Why?

A custom stylesheet allows administrators to customize the cPanel interface in order to align it more closely with their own branding. It can also be used as a kludge to hide some page elements that administrators don't want their users to interact with. Elements hidden using CSS are still visible in the source code, so this is not a perfect or long-term solution. But custom CSS offers a quick, simple way of modifying the interface without worrying about introducing serious new bugs or security risks.

Details:

The Jupiter theme for the main cPanel interface on my system is stored here:
/usr/local/cpanel/base/frontend/jupiter

My strategy for making changes here requires good familiarity with the CSS preprocessor LESS and with CSS minification.

The main cPanel Jupiter files already include a CSS override file named base_overrides.min.css located here:
.../jupiter/css/base_overrides.min.css

cPanel seems to use this for its own overrides to a few elements of Jupiter that for whatever reason aren't fixed at source.

The LESS files that generate base_overrides are located in a subfolder here:
.../jupiter/css/base_overrides
and are called from here:
.../jupiter/css/base_overrides.less

That LESS file simply calls the Index file found in the base_overrides folder:
.../jupiter/css/base_overrides/index.less

Rather than editing page templates or scripts, to add a custom stylesheet, you can simply add your own CSS overrides to the base_overrides that cPanel already includes.

To do this, you create your own LESS partial file (I begin the filename with an underscore following common SASS practice and to match the cPanel coding style here), add your CSS or LESS to it, and then add that file to the base_overrides folder here like so:
.../jupiter/css/base_overrides/_my_cpanel_overrides.less

THEN explicitly import your new LESS file by adding an import reference to it at the end of the index.less file in the same folder. In my install, these are lines 10 and 11 of index.less:

// My custom overrides to Jupiter
@import "_my_cpanel_overrides.less";

Then compile the base_overrides.less file and upload the base_overrides.min.css to your server in the same location where you found it.

I found that in order to compile base_overrides.less locally, I needed to add the following two LESS files that are referenced by base_overrides in addition to adding all the base_overrides folders, subfolders and files:
.../jupiter/libraries/base-styles/variables.less
.../jupiter/shared/css/jupiter.less

As an example of what you can do with this cPanel CSS override file, I have added the following code to _my_cpanel_overrides.less in order to hide the Horde notification that currently cannot be disabled by owners or properly dismissed by users:

// Hide Horde Banner
#cpHordeBanner {
    display: none !important;
  }

It is unclear how often the base_overrides.min.css file will be overwritten by cPanel updates, or if it will in fact be removed entirely at some point in the future. But since these edits result in a change only to that single CSS file, then the worst that will happen if they are overwritten is that your users will see the default cPanel interface instead of your customized version.

 

[pkiff]

[Reserved for revision notes]

 

[mulesheddotcom]

This is very interesting...

 

[pkiff]

A quick update for anyone who stumbles upon this thread. Since at least August 2023 (cPanel (version 114 - RELEASE tier), root users can use an easier, built-in method to add a custom CSS stylesheet to the Jupiter theme.

This new method uses cPanel's "content includes" feature to insert your own stylesheet via the "Global head" template.

Documentation on "content includes" from cPanel:

Guide to cPanel Interface Customization - Content Includes

With its world-class support and rich feature set, cPanel & WHM has been the industry-leading web hosting platform for over 20 years. Trusted worldwide by our technology partners WordPress, CloudLinux, LiteSpeed, and more.

api.docs.cpanel.net

To add a custom stylesheet using the new method, you start by creating a new cpanel_jupiter_head.html.tt file and adding it to /var/cpanel/customizations/content_includes . The documentation says that this folder won't exist in a default install, but it already existed in my install and already had a couple files in it.

Edit that blank file by adding a standard link reference line that loads your custom stylesheet, similar to how you would add a line to the <head> of any HTML page. You can use regular HTML and it will be inserted as-is. In my example below, I'm using the theme_magic_url function to help dynamically manage the path to the CSS file. You need the square brackets and % symbols and the provided syntax for that function to work. This is the entire contents of my file:

<link rel="stylesheet" type="text/css" href="[% theme_magic_url('css/my_custom.css') %]" />

And finally add your my_custom.css file to the right folder. The path I'm using that incorporates the theme_magic_url function loads the CSS file from the following folder in my installation:
/usr/local/cpanel/base/frontend/jupiter/css

The stylesheet line will be inserted close to the end of the <head>, and will be the last CSS file loaded, so any styles you include should supersede those in the other Jupiter stylesheets,

If you don't use the theme_magic_url, then you should provide an absolute path rather than a relative path because some template pages are generated from within subfolders as cPanel users browse their control panel.

It's not clear to me if my custom CSS file will be overwritten by cPanel version updates or not. I would be interested in learning if there is a better path for custom stylesheets or other similar custom theme files to be stored.