White-Label & Customization System

Sprint 14: White-Label & Customization (60 story points) - v0.9.0

Complete white-label branding and customization system for multi-tenant applications with custom domains, themes, and email templates.

Overview
Features
Architecture
CLI Commands
Database Schema
Usage Examples
API Integration
Best Practices

Overview

The nself White-Label System provides comprehensive branding customization capabilities for SaaS platforms, allowing you to:

Create multiple brands for multi-tenant applications
Configure custom domains with automatic SSL provisioning
Customize themes with CSS variables and dark/light modes
Personalize email templates with multi-language support
Manage brand assets (logos, images, fonts, custom CSS)

Key Benefits

✅ Multi-tenant support - Separate branding per tenant
✅ Zero-downtime domain addition - Add domains without restarting
✅ Automatic SSL - Let's Encrypt integration with auto-renewal
✅ Theme system - Pre-built themes + custom theme creation
✅ Email customization - Full control over email appearance
✅ Asset management - Centralized logo and image storage

Features

1. Branding Management

Create and manage brand identities:

# Create a new brand
nself whitelabel branding create "My Company"

# Set brand colors
nself whitelabel branding set-colors \
  --primary #0066cc \
  --secondary #ff6600 \
  --accent #00cc66

# Set brand fonts
nself whitelabel branding set-fonts \
  --primary "Inter, system-ui, sans-serif" \
  --secondary "Georgia, serif"

# Upload logo
nself whitelabel logo upload ./logo.png --type main

# Set custom CSS
nself whitelabel branding set-css ./custom.css

# Preview current branding
nself whitelabel branding preview

Features:

Primary, secondary, and accent colors
Custom fonts (primary, secondary, monospace)
Multiple logo types (main, icon, email, favicon)
Custom CSS injection
Color validation (hex format)
CSS variable auto-generation

2. Custom Domains

Configure custom domains with SSL:

# Add custom domain
nself whitelabel domain add app.mycompany.com

# Verify DNS configuration
nself whitelabel domain verify app.mycompany.com

# Provision SSL certificate
nself whitelabel domain ssl app.mycompany.com --auto-renew

# Check domain health
nself whitelabel domain health app.mycompany.com

# Remove domain
nself whitelabel domain remove app.mycompany.com

Features:

DNS verification (TXT, CNAME, A records)
SSL providers: Let's Encrypt, self-signed, custom
Automatic SSL renewal
Health monitoring
Multiple domains per brand
HTTPS redirect configuration

3. Theme System

Create and manage UI themes:

# Create custom theme
nself whitelabel theme create my-theme

# Edit theme configuration
nself whitelabel theme edit my-theme

# Preview theme
nself whitelabel theme preview my-theme

# Activate theme
nself whitelabel theme activate my-theme

# Export theme
nself whitelabel theme export my-theme > theme.json

# Import theme
nself whitelabel theme import theme.json

Built-in Themes:

Light - Clean and bright (default)
Dark - Easy on the eyes
High Contrast - Maximum accessibility

Theme Variables:

Colors (primary, secondary, accent, background, text, etc.)
Typography (fonts, sizes, weights, line heights)
Spacing (xs, sm, md, lg, xl, xxl)
Borders (radius, width)
Shadows (sm, md, lg)

4. Email Templates

Customize email templates:

# List available templates
nself whitelabel email list

# Edit template
nself whitelabel email edit welcome

# Preview template with sample data
nself whitelabel email preview welcome

# Send test email
nself whitelabel email test welcome [email protected]

# Set language
nself whitelabel email set-language es

Default Templates:

welcome - Welcome new users
password-reset - Password reset with secure link
verify-email - Email verification
invite - User invitations
password-change - Password change confirmation
account-update - Account update notifications
notification - Generic notifications
alert - Alert/warning messages

Template Variables:

Global variables available in all templates:

{{BRAND_NAME}} - Brand/company name
{{LOGO_URL}} - URL to brand logo
{{APP_URL}} - Main application URL
{{CURRENT_YEAR}} - Current year
{{USER_NAME}} - User's display name
{{SUPPORT_EMAIL}} - Support email

Template-specific variables:

{{RESET_URL}} - Password reset link
{{VERIFY_URL}} - Email verification link
{{NOTIFICATION_TITLE}} - Notification headline
And more...

5. Asset Management

Upload and manage assets:

# Upload logo
nself whitelabel logo upload ./logo.png --type main
nself whitelabel logo upload ./icon.png --type icon
nself whitelabel logo upload ./email-logo.png --type email

# List logos
nself whitelabel logo list

# Remove logo
nself whitelabel logo remove <logo-id>

Supported Asset Types:

Logos: PNG, JPG, JPEG, SVG, WebP
Fonts: TTF, OTF, WOFF, WOFF2
CSS: Custom stylesheets
SSL Certificates: PEM format

Architecture

Component Structure

src/
├── cli/
│   └── whitelabel.sh              # Main CLI entry point
├── lib/
│   └── whitelabel/
│       ├── branding.sh             # Brand management
│       ├── email-templates.sh      # Email customization
│       ├── domains.sh              # Custom domains & SSL
│       └── themes.sh               # Theme system
└── postgres/
    └── migrations/
        └── 016_create_whitelabel_system.sql

Database Tables

whitelabel_brands - Brand configurations
whitelabel_domains - Custom domains with SSL
whitelabel_themes - UI themes and CSS variables
whitelabel_email_templates - Email templates
whitelabel_assets - Logos, images, fonts, files

File System Structure

branding/
├── config.json                    # Main branding config
├── logos/                         # Logo files
│   ├── logo-main.png
│   ├── logo-icon.png
│   └── logo-email.png
├── css/                           # CSS files
│   ├── variables.css              # Auto-generated from config
│   └── custom.css                 # User custom CSS
├── fonts/                         # Font files
├── assets/                        # Other assets
├── themes/                        # Theme configurations
│   ├── light/
│   │   ├── theme.json
│   │   └── theme.css
│   ├── dark/
│   │   ├── theme.json
│   │   └── theme.css
│   └── .active                    # Active theme name
├── email-templates/               # Email templates
│   └── languages/
│       ├── en/                    # English templates
│       │   ├── welcome.html
│       │   ├── welcome.txt
│       │   └── welcome.json
│       └── es/                    # Spanish templates
└── domains/                       # Domain configurations
    ├── domains.json
    ├── ssl/                       # SSL certificates
    │   └── app.mycompany.com/
    │       ├── cert.pem
    │       ├── key.pem
    │       └── chain.pem
    └── dns-challenges/            # DNS verification tokens

CLI Commands

Branding Commands

# Create brand
nself whitelabel branding create <brand-name>

# Set colors
nself whitelabel branding set-colors --primary <color> --secondary <color>

# Set fonts
nself whitelabel branding set-fonts --primary <font> --secondary <font>

# Upload logo
nself whitelabel branding upload-logo <path>

# Set custom CSS
nself whitelabel branding set-css <path>

# Preview branding
nself whitelabel branding preview

Domain Commands

# Add domain
nself whitelabel domain add <domain>

# Verify domain
nself whitelabel domain verify <domain>

# Provision SSL
nself whitelabel domain ssl <domain> [--auto-renew]

# Check health
nself whitelabel domain health <domain>

# Remove domain
nself whitelabel domain remove <domain>

Email Commands

# List templates
nself whitelabel email list

# Edit template
nself whitelabel email edit <template-name>

# Preview template
nself whitelabel email preview <template-name>

# Test template
nself whitelabel email test <template-name> <email>

# Set language
nself whitelabel email set-language <lang-code>

Theme Commands

# Create theme
nself whitelabel theme create <theme-name>

# Edit theme
nself whitelabel theme edit <theme-name>

# Activate theme
nself whitelabel theme activate <theme-name>

# Preview theme
nself whitelabel theme preview <theme-name>

# Export theme
nself whitelabel theme export <theme-name>

# Import theme
nself whitelabel theme import <path>

Logo Commands

# Upload logo
nself whitelabel logo upload <path> [--type main|icon|email]

# List logos
nself whitelabel logo list

# Remove logo
nself whitelabel logo remove <logo-id>

System Commands

# Initialize system
nself whitelabel init

# View settings
nself whitelabel settings

# List all resources
nself whitelabel list

# Export configuration
nself whitelabel export --format json

# Import configuration
nself whitelabel import <config-file>

Database Schema

whitelabel_brands

Primary table for brand configurations.

Columns:

id - UUID primary key
tenant_id - Unique tenant identifier
brand_name - Brand display name
tagline, description - Brand information
primary_color, secondary_color, accent_color - Brand colors
primary_font, secondary_font, code_font - Typography
logo_main_id, logo_icon_id, etc. - Asset references
active_theme_id - Current theme reference
is_active, is_primary - Status flags
Timestamps and audit fields

whitelabel_domains

Custom domain management with SSL.

Columns:

id - UUID primary key
brand_id - Brand reference
domain - Domain name (unique)
dns_verified, dns_verification_token - DNS status
ssl_enabled, ssl_provider, ssl_expiry_date - SSL config
ssl_cert_id, ssl_key_id, ssl_chain_id - Certificate references
health_status, last_health_check_at - Health monitoring
status - pending, verified, active, suspended, failed
Timestamps and audit fields

whitelabel_themes

Theme configurations with CSS variables.

Columns:

id - UUID primary key
brand_id - Brand reference
theme_name, display_name, description - Theme info
mode - light, dark, auto
colors - JSONB color variables
typography - JSONB typography variables
spacing - JSONB spacing variables
borders - JSONB border variables
shadows - JSONB shadow variables
custom_css, compiled_css - CSS content
is_active, is_default, is_system - Status flags
Timestamps and audit fields

whitelabel_email_templates

Email template customization.

Columns:

id - UUID primary key
brand_id - Brand reference
template_name, display_name, category - Template info
language_code - ISO 639-1 language code
subject, from_name, from_email - Email headers
html_content, text_content - Template content
variables - JSONB array of variable names
sample_data - JSONB sample data for preview
sent_count, last_sent_at - Usage stats
Timestamps and audit fields

whitelabel_assets

Asset storage and management.

Columns:

id - UUID primary key
brand_id - Brand reference
asset_name, asset_type, asset_category - Asset info
file_name, file_path, file_size, mime_type - File info
image_width, image_height - Image metadata
storage_provider, storage_bucket, storage_key - Storage config
cdn_url, cdn_enabled - CDN configuration
is_public, access_url - Access control
version, previous_version_id - Version control
Timestamps and audit fields

Usage Examples

Example 1: Complete Brand Setup

# 1. Initialize white-label system
nself whitelabel init

# 2. Create brand
nself whitelabel branding create "TechCorp"

# 3. Configure colors
nself whitelabel branding set-colors \
  --primary #1a73e8 \
  --secondary #34a853 \
  --accent #fbbc04

# 4. Upload logos
nself whitelabel logo upload ./assets/logo.png --type main
nself whitelabel logo upload ./assets/icon.png --type icon

# 5. Configure custom domain
nself whitelabel domain add app.techcorp.com
nself whitelabel domain verify app.techcorp.com
nself whitelabel domain ssl app.techcorp.com --auto-renew

# 6. Customize email template
nself whitelabel email edit welcome

# 7. Create custom theme
nself whitelabel theme create techcorp-theme
nself whitelabel theme edit techcorp-theme
nself whitelabel theme activate techcorp-theme

# 8. Preview everything
nself whitelabel branding preview

Example 2: Multi-Tenant Setup

# Tenant 1
nself whitelabel branding create "Company A" --tenant tenant-a
nself whitelabel domain add app.companya.com --tenant tenant-a

# Tenant 2
nself whitelabel branding create "Company B" --tenant tenant-b
nself whitelabel domain add app.companyb.com --tenant tenant-b

# Each tenant has independent branding

Example 3: Export/Import Configuration

# Export complete branding
nself whitelabel export --format json > branding-backup.json

# Import on different server
nself whitelabel import branding-backup.json

Example 4: Theme Development

# Create custom theme
nself whitelabel theme create my-custom-theme

# Edit theme.json to customize
nself whitelabel theme edit my-custom-theme

# Preview changes
nself whitelabel theme preview my-custom-theme

# Export for sharing
nself whitelabel theme export my-custom-theme > my-theme.json

# Import on another instance
nself whitelabel theme import my-theme.json

# Activate
nself whitelabel theme activate my-custom-theme

API Integration

GraphQL Queries

# Get brand information
query GetBrand($tenantId: String!) {
  whitelabel_brands(where: {tenant_id: {_eq: $tenantId}}) {
    id
    brand_name
    tagline
    primary_color
    secondary_color
    accent_color
    logo_main {
      access_url
    }
    active_theme {
      theme_name
      colors
      typography
    }
  }
}

# Get custom domains
query GetDomains($brandId: uuid!) {
  whitelabel_domains(where: {brand_id: {_eq: $brandId}, is_active: {_eq: true}}) {
    domain
    ssl_enabled
    ssl_expiry_date
    health_status
  }
}

# Get email template
query GetEmailTemplate($brandId: uuid!, $templateName: String!, $language: String!) {
  whitelabel_email_templates(
    where: {
      brand_id: {_eq: $brandId}
      template_name: {_eq: $templateName}
      language_code: {_eq: $language}
    }
  ) {
    subject
    html_content
    text_content
    variables
  }
}

REST API Integration

The white-label system integrates with your application through:

Brand Context Injection - Automatically inject brand info based on domain/tenant
Theme CSS Serving - Serve compiled theme CSS via CDN
Email Rendering - Replace template variables before sending
Asset URLs - Generate signed URLs for private assets

Best Practices

1. Branding

✅ DO:

Use consistent color schemes (primary, secondary, accent)
Validate hex colors before setting
Use web-safe fonts with fallbacks
Optimize logo images (WebP, SVG preferred)
Test branding on dark/light backgrounds

❌ DON'T:

Use too many custom colors (stick to theme variables)
Upload unoptimized large images
Use custom fonts without fallbacks
Hardcode colors in custom CSS

2. Custom Domains

✅ DO:

Verify DNS before provisioning SSL
Enable auto-renewal for Let's Encrypt
Set up health monitoring
Use HTTPS redirects
Document DNS requirements for users

❌ DON'T:

Skip DNS verification
Use self-signed certificates in production
Forget to renew certificates
Allow HTTP in production

3. Themes

✅ DO:

Use CSS variables for all colors/spacing
Test themes for accessibility (WCAG 2.1 AA)
Provide both light and dark variants
Document custom theme variables
Version theme changes

❌ DON'T:

Hardcode values in theme CSS
Break accessibility with custom themes
Create themes without dark mode support
Forget to test on different screen sizes

4. Email Templates

✅ DO:

Provide both HTML and plain text versions
Test templates with sample data
Use semantic HTML
Keep templates mobile-responsive
Document all template variables

❌ DON'T:

Use only HTML (always include plain text)
Hardcode brand information
Use complex CSS (email clients strip it)
Forget to test on multiple email clients

5. Asset Management

✅ DO:

Optimize images before upload
Use version control for assets
Enable CDN for public assets
Document asset dimensions/formats
Clean up unused assets

❌ DON'T:

Upload raw, unoptimized files
Store sensitive data in public assets
Use inconsistent file naming
Forget to backup assets

Security Considerations

Asset Access Control

Public assets: Served directly via CDN
Private assets: Require signed URLs
SSL certificates: Stored with restricted permissions
Version control: Previous versions accessible only to admins

Domain Verification

DNS verification required before SSL
TXT records for ownership proof
Challenge tokens expire after 24 hours
Only verified domains can be activated

Multi-Tenant Isolation

Each tenant has separate brand configuration
Assets are scoped by brand_id
Themes cannot be shared across tenants without explicit import
Domains must be unique across all brands

Troubleshooting

Common Issues

DNS verification fails:

# Check DNS propagation
dig TXT _nself-verification.yourdomain.com

# Verify A/CNAME record
dig yourdomain.com A

# Force re-verification
nself whitelabel domain verify yourdomain.com

SSL provisioning fails:

# Check certbot installation
which certbot

# Check domain accessibility
curl -I http://yourdomain.com

# Use self-signed for testing
SSL_PROVIDER=selfsigned nself whitelabel domain ssl yourdomain.com

Theme not applying:

# Check active theme
cat branding/themes/.active

# Regenerate CSS
nself whitelabel theme edit <theme-name>

# Verify CSS file exists
ls -la branding/themes/<theme-name>/theme.css

Email template variables not replaced:

# Check template variables
nself whitelabel email preview <template-name>

# Verify variable names match
cat branding/email-templates/languages/en/<template>.json

Performance Optimization

CDN Integration

Enable CDN for assets to improve load times:

# Configure CDN in brand settings
cdn_enabled=true
cdn_url=https://cdn.yourdomain.com

CSS Minification

Minify compiled theme CSS for production:

# Install cssmin
npm install -g clean-css-cli

# Minify theme CSS
cleancss -o theme.min.css theme.css

Asset Optimization

Optimize images before upload:

# PNG optimization
optipng logo.png

# JPEG optimization
jpegoptim --max=85 photo.jpg

# WebP conversion
cwebp logo.png -o logo.webp

Migration Guide

From Manual Branding

If you're currently using manual branding configuration:

Export existing configuration
Initialize white-label system
Import configuration
Verify branding
Update application to use white-label API

From Other Platforms

Import from common platforms:

# Export from other platform (example format)
{
  "brand": {
    "name": "Company",
    "colors": {...},
    "fonts": {...}
  }
}

# Convert to nself format
nself whitelabel import converted-config.json

Future Enhancements

Planned features for future releases:

Support

For issues, questions, or contributions:

Documentation: https://docs.nself.org/whitelabel
GitHub Issues: https://github.com/nself-org/cli/issues
Discord: https://discord.gg/nself
Email: [email protected]

License

The nself White-Label System is part of the nself project and is licensed under the MIT License.

Last Updated: January 29, 2026 Version: 0.9.0 Sprint: 14 - White-Label & Customization (60 story points)

WHITELABEL SYSTEM - nself-org/cli GitHub Wiki

White-Label & Customization System

Table of Contents

Overview

Key Benefits

Features

1. Branding Management

2. Custom Domains

3. Theme System

4. Email Templates

5. Asset Management

Architecture

Component Structure

Database Tables

File System Structure

CLI Commands

Branding Commands

Domain Commands

Email Commands

Theme Commands

Logo Commands

System Commands

Database Schema

whitelabel_brands

whitelabel_domains

whitelabel_themes

whitelabel_email_templates

whitelabel_assets

Usage Examples

Example 1: Complete Brand Setup

Example 2: Multi-Tenant Setup

Example 3: Export/Import Configuration

Example 4: Theme Development

API Integration

GraphQL Queries

REST API Integration

Best Practices

1. Branding

2. Custom Domains

3. Themes

4. Email Templates

5. Asset Management

Security Considerations

Asset Access Control

Domain Verification

Multi-Tenant Isolation

Troubleshooting

Common Issues

Performance Optimization

CDN Integration

CSS Minification

Asset Optimization

Migration Guide

From Manual Branding

From Other Platforms

Future Enhancements

Support

License

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️