docuseal/docs/WHITELABEL.md

White-Label Configuration Guide

Overview

This fork of DocuSeal uses a centralised white-label configuration system that lets you rebrand the entire application for any client by editing a single YAML file. No need to create a separate repo for each client.

Architecture

config/whitelabel.yml          ← Single source of truth (brand, URLs, theme, PDF, features)
lib/whitelabel.rb              ← Ruby module that loads + exposes the config
config/initializers/whitelabel.rb  ← Patches Docuseal module at boot so existing code uses new values
app/helpers/whitelabel_helper.rb   ← View helper (use `wl.xxx` in any ERB template)
config/locales/whitelabel.yml  ← Locale overrides for branded i18n keys (EN + FR)
public/intebec.css             ← CSS theme overrides (DaisyUI custom properties)

How to Rebrand for a New Client

1. Edit config/whitelabel.yml

Change the values under each section:

Section	What it controls
brand	Name, tagline, description, page titles
urls	Website, support email, privacy/terms, socials
email	From address, email attribution
assets	Logo, favicons, preview image
theme	DaisyUI colour palette (HSL values)
pdf	Signing reason, audit trail footer, cert name
pwa	PWA manifest name, colours
webhooks	User-Agent string
features	Toggle GitHub button, AI link, powered-by text

2. Replace Asset Files

Put your client's files in /public:

• logo.svg — navbar + form logo
• favicon.ico, favicon-16x16.png, favicon-32x32.png, favicon-96x96.png
• favicon.svg — SVG favicon
• apple-icon-180x180.png — iOS home screen icon
• preview.png — Open Graph social preview

3. Update Theme Colours

Two options:

Option A — Edit theme: in config/whitelabel.yml (DaisyUI tokens, HSL format):

theme:
  primary: "216 77% 52%"
  secondary: "220 12% 45%"
  accent: "160 50% 40%"

Option B — Edit public/intebec.css for fine-grained CSS overrides.

4. Update Locale Overrides

Edit config/locales/whitelabel.yml to change branded text in both English and French. This file overrides the base config/locales/i18n.yml — Rails merges them automatically.

5. Restart

After editing, restart the app:

docker compose down && docker compose up -d --build

Or in a Rails console:

Whitelabel.reload!

Usage in Code

In ERB views

<%= wl.brand_name %>
<%= wl.logo_path %>
<%= wl.support_email %>
<%= wl.page_title(signed_in: true) %>

In Ruby (controllers, mailers, lib)

Whitelabel.brand_name      # => "Intébec"
Whitelabel.website_url     # => "https://intebec.ca"
Whitelabel.email_from      # => "Intébec <info@intebec.ca>"
Whitelabel.sign_reason("John") # => "Signed by John with Intébec"
Whitelabel.theme(:primary) # => "216 77% 52%"

In JavaScript

Brand values are available via <meta> tags in the page head:

document.querySelector('meta[name="brand-name"]').content; // "Intébec"
document.querySelector('meta[name="brand-website-url"]').content; // "https://intebec.ca"

Upstream Merge Strategy

This system is designed to minimise merge conflicts with the upstream DocuSeal repo:

1. New files (no conflicts): config/whitelabel.yml, lib/whitelabel.rb, config/initializers/whitelabel.rb, app/helpers/whitelabel_helper.rb, config/locales/whitelabel.yml
2. Patched files (potential conflicts, but isolated changes):
   • lib/docuseal.rb — only added a comment block; the product_name method is overridden at runtime
   • View templates — changes are surgical (replacing one hardcoded string with a Whitelabel.xxx call)
3. Untouched internal identifiers: data-theme="docuseal", Docuseal module name, #docuseal_modal_container, docuseal_clipboard localStorage keys — all kept as-is for compatibility

When Upstream Adds New Branded Content

1. Check if new views/lib files have hardcoded "DocuSeal" text
2. Replace with Whitelabel.brand_name or wl.brand_name
3. If it's an i18n key, add the override to config/locales/whitelabel.yml

Feature Flags

Toggle upstream features without removing code:

features:
  show_github_button: false # Hide "Star on GitHub"
  show_powered_by: true # Show/hide "Powered by" on signing pages
  show_ai_link: false # Hide "Ask AI" in user menu
  show_discord_link: false # Hide Discord link

File Reference

File	Purpose	Upstream risk
config/whitelabel.yml	All brand config	New file — zero risk
lib/whitelabel.rb	Config loader	New file — zero risk
config/initializers/whitelabel.rb	Boot-time patching	New file — zero risk
app/helpers/whitelabel_helper.rb	View helper	New file — zero risk
config/locales/whitelabel.yml	i18n overrides	New file — zero risk
public/intebec.css	Theme CSS	Custom file — zero risk
lib/docuseal.rb	Added comment	Low risk — comment only
app/views/shared/_logo.html.erb	Dynamic logo path	Low risk
app/views/shared/_meta.html.erb	Dynamic meta tags	Low risk
app/views/shared/_title.html.erb	Dynamic brand name	Low risk
app/views/layouts/application.html.erb	Added meta tags	Low risk
app/views/layouts/form.html.erb	Added meta tags	Low risk