Branding Pro/Ent only

Branding can be localized, allowing different branding for each supported language.

Branding should be applied on the filesystem using Cockpit File Browser or via ssh.

All brandable texts and images are stored in translation.yml yaml files.

For every supported language, there is a separate translation.yml file, one for every suported language. The base directory for the locale files is different for the admin UI and the portal UI:

For the admin UI:

/opt/ciphermail/ui/admin/locales/

For the portal UI:

/opt/ciphermail/ui/portal/locales/

The default locale is en. If a key is available under the default en locale but not under a different locale, for example de, the value from the en locale will be used for the other locale.

Texts (and some images) can be overridden by creating an override.yml file in the directory for the locale.

For example, for the portal application, create the file /opt/ciphermail/ui/portal/locales/en/override.yml

To override a specific text, add a line with an updated value for the key which need to be overridden:

portal.title: 'Update Portal Application Title'

Tip

To see which values can be overridden, see the translation.yml file from the same directory.

Images

Images should be provided as a data‑URL. To encode an image, follow these steps:

  1. Copy the favicon to the gateway

  2. Log in to the shell, then run the following command:

    ciphermail-cli tool html data-url encode --input-file <image-file>

    Replace <image-file> with the full path of the uploaded image file.

    The above command will return the encoded image.

  3. Copy the encoded value to the override.yml file for the value you need to override

Tip

To copy logo files to the gateway, you can use Cockpit File Browser or use an scp client.

To create and edit the override file , you can use the built-in Cockpit text editor. To create a file select Create file from the top-right menu (the three dots). To edit a file, right-click the file and select Open text file.

To access the system shell, use Cockpit Terminal or use an SSH client.

Example override file:

portal.home.content: '<p>This is shown on the portal home page<p>This <b>can</b> contain HTML <a href="https://www.example.com>link</a>'
portal.home.title: 'Updated Portal Home Title'
portal.legal-notice: '<p>This is shown on the login and
  signup page<p>This <b>can</b> contain HTML
  <a href="https://www.example.com>link</a>'
portal.title: 'Update Portal Application Title'
login.logo: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABk.......

Styles

CipherMail UI uses the Bootstrap front-end toolkit for its styling. This means the application’s colors, fonts, spacing, and other visual elements are based on Bootstrap’s built-in design system. If you want to change the look and feel of CipherMail, you can do so by adjusting Bootstrap’s CSS custom variables.

By overriding these variables, you can apply your own branding, such as updating primary and secondary colors, adjusting border rounding, or changing default text and background colors, without having to rewrite the entire stylesheet. In practice, this approach lets you customize the appearance in a predictable and maintainable way, while still benefiting from Bootstrap’s responsive layout and consistent component styling.

Tip

If updating the CSS custom variables does not meet your needs, you can replace the Bootstrap CSS library with your own custom stylesheet.

In the CipherMail user interface, you can change the default look and feel by editing the CSS variable overrides in the variables.css files. Separate variables.css files are used for the admin interface and the portal interface.

Do not edit variables.css directly, because it is a symbolic link to the default factory file ciphermail-variables.css. If you want to use custom variables, follow the procedure below:

  1. Copy factory variables file to a custom variables file

  2. Add ansible override file to use the custom variables file

  3. Modify the custom variables

Copy factory variables file

cd /opt/ciphermail/ui/portal/style
sudo cp ciphermail-variables.css custom-variables.css

Add ansible override file

Create and edit the override file /etc/ciphermail/ansible/group_vars/all/portal-branding.yml

Add the following line:

ciphermail_ui__portal_variables_css__path: '{{ ciphermail_ui__portal_base_dir }}/style/custom-variables.css'

Now run the playbook:

sudo cm-run-playbook

After running the playbook, the variables.css symbolic link should point to custom-variables.css.

Modify the custom variables

The default variables file contains the CipherMail specific CSS custom variables:

:root {
    --cm-app-color: #0daa7e;
    --cm-sidebar-item-color: #929bb6;
    --cm-sidebar-item-color-active: var(--cm-app-color);
    --cm-sidebar-item-color-hover: var(--cm-sidebar-item-color-active);
    --cm-sidebar-item-background-color-active: #353e52;
    --cm-sidebar-background-color: #243244;
    --cm-sidebar-icon-width: 24px;
    --cm-sidebar-max-width: 250px;
    --cm-sidebar-left-border-width: 2px;
    --cm-sidebar-sub-lavel-settings-item-color: #5b6987;
    --cm-sidebar-sub-lavel-settings-item-color-active: white;
    --cm-sidebar-sub-lavel-settings-item-background-color-active: #929bb6;

    --cm-login-logo-width: 250px;
    --cm-login-column-max-width: 600px;

    --cm-page-title-background-color: var(--cm-app-color);
    --cm-page-title-radius: 40px;

    --cm-max-page-width: 1600px;
    --cm-settings-view-max-width: var(--cm-max-page-width);

    --cm-table-header-height: 3em;

    --cm-table-icon-size: 20px;
}

For example, changing the cm-app-color setting updates some of the default colors used throughout the user interface.

Tip

Web browsers often store (cache) CSS files to make pages load faster. Because of this, changes to CSS variables may not appear immediately. If you do not see your updates after changing or overriding CSS variables, try one of the following:

  1. Clear your browser cache and reload the page.

  2. Open the browser’s Developer Tools, go to the Network tab, enable “Disable cache”, and then reload the page (keep Developer Tools open while reloading).

If the browser still uses an old copy of the variables file, you can force it to download the latest version by changing the “cache-busting” number in the URL. Edit /opt/ciphermail/ui/portal/index.html and find the reference to the variables stylesheet, for example:

/style/variables.css?1771766732544

Increase the number after the question mark (for example, change 1771766732544 to 1771766732545), save the file, and reload the page. This makes the browser treat it as a new file and fetch the updated CSS variables.

Override Bootstrap variables

Bootstrap uses CSS custom variables (also known as CSS variables) to control many parts of its default look and feel, such as colors, spacing, borders, and typography.

If you want to change the default styling, you can override these variables in your own stylesheet. Your custom values will then be used wherever Bootstrap references those variables, allowing you to adjust the appearance without modifying Bootstrap’s source files.

For a complete overview of the available Bootstrap CSS custom variables, see the official Bootstrap documentation: https://getbootstrap.com/docs/5.3/customize/css-variables/

For example, to switch to a dark style, add the following variables to your custom variables file:

--bs-body-color: #dee2e6;
--bs-body-color-rgb: 222, 226, 230;
--bs-body-bg: #212529;
--bs-body-bg-rgb: 33, 37, 41;
--bs-emphasis-color: #fff;
--bs-emphasis-color-rgb: 255, 255, 255;
--bs-secondary-color: rgba(222, 226, 230, 0.75);
--bs-secondary-color-rgb: 222, 226, 230;
--bs-secondary-bg: #343a40;
--bs-secondary-bg-rgb: 52, 58, 64;
--bs-tertiary-color: rgba(222, 226, 230, 0.5);
--bs-tertiary-color-rgb: 222, 226, 230;
--bs-tertiary-bg: #2b3035;
--bs-tertiary-bg-rgb: 43, 48, 53;
--bs-primary-text-emphasis: #6ea8fe;
--bs-secondary-text-emphasis: #a7acb1;
--bs-success-text-emphasis: #75b798;
--bs-info-text-emphasis: #6edff6;
--bs-warning-text-emphasis: #ffda6a;
--bs-danger-text-emphasis: #ea868f;
--bs-light-text-emphasis: #f8f9fa;
--bs-dark-text-emphasis: #dee2e6;
--bs-primary-bg-subtle: #031633;
--bs-secondary-bg-subtle: #161719;
--bs-success-bg-subtle: #051b11;
--bs-info-bg-subtle: #032830;
--bs-warning-bg-subtle: #332701;
--bs-danger-bg-subtle: #2c0b0e;
--bs-light-bg-subtle: #343a40;
--bs-dark-bg-subtle: #1a1d20;
--bs-primary-border-subtle: #084298;
--bs-secondary-border-subtle: #41464b;
--bs-success-border-subtle: #0f5132;
--bs-info-border-subtle: #087990;
--bs-warning-border-subtle: #997404;
--bs-danger-border-subtle: #842029;
--bs-light-border-subtle: #495057;
--bs-dark-border-subtle: #343a40;
--bs-heading-color: inherit;
--bs-link-color: #6ea8fe;
--bs-link-hover-color: #8bb9fe;
--bs-link-color-rgb: 110, 168, 254;
--bs-link-hover-color-rgb: 139, 185, 254;
--bs-code-color: #e685b5;
--bs-highlight-color: #dee2e6;
--bs-highlight-bg: #664d03;
--bs-border-color: #495057;
--bs-border-color-translucent: rgba(255, 255, 255, 0.15);
--bs-form-valid-color: #75b798;
--bs-form-valid-border-color: #75b798;
--bs-form-invalid-color: #ea868f;
--bs-form-invalid-border-color: #ea868f;