White Labeling

White labeling allows you to replace default Cozystack branding with your own logos and text across the Dashboard UI and Keycloak authentication pages.

Overview

Branding is configured through the branding field in the Platform Package (spec.components.platform.values.branding). The configuration propagates automatically to:

• Dashboard: logo, page title, footer text, favicon, and tenant identifier
• Keycloak: realm display name on authentication pages

Configuration

Edit your Platform Package to add or update the branding section:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
  name: cozystack.cozystack-platform
spec:
  variant: isp-full # use your variant
  components:
    platform:
      values:
        branding:
          # Dashboard branding
          titleText: "My Company Dashboard"
          footerText: "My Company Platform"
          tenantText: "Production v1.0"
          logoText: ""
          logoSvg: "<base64-encoded SVG>"
          iconSvg: "<base64-encoded SVG>"
          # Keycloak branding
          brandName: "My Company"
          brandHtmlName: "<div style='font-weight:bold;'>My Company</div>"

Apply the changes:

kubectl apply --server-side --filename platform-package.yaml

Configuration Fields

Dashboard Fields

Keycloak Fields

Preparing SVG Logos

Theme-Aware SVG Variables

The Dashboard supports template variables in SVG content that adapt to light and dark themes:

• {token.colorText} — replaced at runtime with the current theme’s text color

Example SVG using a theme-aware variable:

<svg width="150" height="30" viewBox="0 0 150 30" fill="none"
     xmlns="http://www.w3.org/2000/svg">
  <path d="M10 5h30v20H10z" fill={token.colorText} />
  <text x="50" y="20" fill={token.colorText}>My Company</text>
</svg>

Converting SVG to Base64

Encode your SVG files to base64 strings:

base64 < logo.svg | tr -d '\n'

Example Workflow

# Encode logos
LOGO_B64=$(base64 < logo.svg | tr -d '\n')
ICON_B64=$(base64 < icon.svg | tr -d '\n')

# Patch the Platform Package
kubectl patch packages.cozystack.io cozystack.cozystack-platform \
  --type merge --server-side \
  --patch "{
    \"spec\": {
      \"components\": {
        \"platform\": {
          \"values\": {
            \"branding\": {
              \"logoSvg\": \"$LOGO_B64\",
              \"iconSvg\": \"$ICON_B64\"
            }
          }
        }
      }
    }
  }"

Verification

After applying changes, verify that branding is correctly configured:

1. Check the Platform Package:

   kubectl get packages.cozystack.io cozystack.cozystack-platform \
     --output jsonpath='{.spec.components.platform.values.branding}' | jq .
   

2. Dashboard: open the Dashboard URL and verify the logo, title, footer, and favicon.

3. Keycloak: open the Keycloak login page and verify the realm display name.

Migration from v0

In Cozystack v0, branding was configured via a standalone cozystack-branding ConfigMap in the cozy-system namespace. In v1, this ConfigMap is no longer used. The migration script automatically converts the old ConfigMap values into the Platform Package branding field.

If you previously used the ConfigMap approach, no manual migration is needed — the upgrade process handles it automatically.