Whitelabel & Branding¶

Complete guide to customizing S5 Slidefactory with your brand identity.

Overview¶

S5 Slidefactory supports full whitelabel customization through environment variables. Customize:

Company/Product Name - Appears throughout the UI
Logos - Small (navigation) and large (login page)
Brand Colors - Primary color for buttons, links, accents
Descriptions - Custom taglines and metadata

Configuration Method: Environment variables (no code changes required)

Quick Start¶

Get your branded version running in 5 minutes.

Prerequisites¶

Two logo files: - Small logo (navigation/chat): Square or circular, 64-128px, PNG format - Large logo (login page): Banner format, max 80px height, PNG format

Step 1: Place Logo Files¶

# Option A: Use default paths (easiest)
cp your-small-logo.png static/img/logo.png
cp your-large-logo.png static/img/logo_large.png

# Option B: Use custom subdirectory
mkdir -p static/img/clients/yourcompany/
cp your-small-logo.png static/img/clients/yourcompany/logo.png
cp your-large-logo.png static/img/clients/yourcompany/logo_large.png

Step 2: Set Environment Variables¶

Add to your .env file:

# Required
CLIENT_NAME="Your Company Name"
CLIENT_PRIMARY_COLOR="#yourcolor"  # Your brand color (hex format)

# Optional (if using custom paths)
CLIENT_LOGO=/static/img/clients/yourcompany/logo.png
CLIENT_LOGO_LARGE=/static/img/clients/yourcompany/logo_large.png
CLIENT_DESCRIPTION="Your Company Presentation Platform"

Step 3: Restart & Verify¶

# Start the app
./start.sh

# Or with Docker
docker-compose restart web

# Verify pages:
# - Login: http://localhost:8080/auth/signin
# - API Docs: http://localhost:8080/docs
# - Manifest: http://localhost:8080/manifest.json

Verification Checklist: - ✅ Your logo appears in navigation - ✅ Your brand color is applied to buttons - ✅ Your company name shows in browser title

Configuration Reference¶

Environment Variables¶

# Client/Company Name
CLIENT_NAME="Slidefactory"                    # Default: "Slidefactory"

# Logo Paths (relative to /static/img/)
CLIENT_LOGO="/static/img/logo.png"            # Small/square logo for navigation
CLIENT_LOGO_LARGE="/static/img/logo_large.png" # Banner logo for login page

# Brand Colors
CLIENT_PRIMARY_COLOR="#ee0000"                # Primary brand color (hex format)
CLIENT_SECONDARY_COLOR="#333333"              # Secondary color
CLIENT_ACCENT_COLOR="#ff6600"                 # Accent color

# Optional: Custom Title and Description
CLIENT_TITLE=""                               # Browser/API title (defaults to CLIENT_NAME if empty)
CLIENT_DESCRIPTION="AI-driven presentation automation platform"

# Support Contact
CLIENT_SUPPORT_EMAIL="support@slidefactory.io"
CLIENT_SUPPORT_URL=""                         # Optional support/help URL

# Favicon
CLIENT_FAVICON="/static/img/favicon.ico"

See Environment Variables Reference → for complete list.

Logo Specifications¶

Small Logo (CLIENT_LOGO)¶

Usage: Navigation bar, chat widget header, favicon source

Requirements: - Format: PNG with transparent background (preferred) or SVG - Dimensions: Square or circular, 64x64 to 128x128 pixels recommended - File size: Keep under 50KB for optimal loading - Colors: Should work well on light and dark backgrounds

Example:

CLIENT_LOGO="/static/img/logo.png"

Large Logo (CLIENT_LOGO_LARGE)¶

Usage: Login page header, welcome screens

Requirements: - Format: PNG with transparent background (preferred) or SVG - Dimensions: Variable width × 60-80px height recommended - Aspect ratio: Wide banner format (e.g., 200×60px) - File size: Keep under 100KB for optimal loading - Colors: Should be visible on white/light backgrounds

Example:

CLIENT_LOGO_LARGE="/static/img/logo_large.png"

Color Configuration¶

Primary Color¶

Usage: Applied throughout the UI: - Navigation highlights - Action buttons - Links and accents - Chat widget elements - PWA theme color (mobile browser chrome)

Requirements: - Format: Hex color code (6 digits with # prefix) - Contrast: Ensure sufficient contrast against white backgrounds (WCAG AA minimum) - Examples: - #ee0000 (Red - default) - #007ACC (Blue) - #2ECC71 (Green) - #9B59B6 (Purple)

Testing: Use a contrast checker to ensure accessibility: - WebAIM Contrast Checker - Minimum ratio: 4.5:1 for normal text, 3:1 for large text

Additional Colors¶

Secondary Color (CLIENT_SECONDARY_COLOR): - Used for secondary UI elements - Default: #333333

Accent Color (CLIENT_ACCENT_COLOR): - Highlights and special emphasis - Default: #ff6600

Deployment Examples¶

Minimal Setup¶

# .env
CLIENT_NAME=Acme Corp
CLIENT_PRIMARY_COLOR=#007ACC

Place logos at static/img/logo.png and static/img/logo_large.png

Full Customization¶

# .env
CLIENT_NAME=Global Solutions
CLIENT_LOGO=/static/img/clients/global/logo.png
CLIENT_LOGO_LARGE=/static/img/clients/global/banner.png
CLIENT_PRIMARY_COLOR=#2ECC71
CLIENT_SECONDARY_COLOR=#27AE60
CLIENT_ACCENT_COLOR=#F39C12
CLIENT_DESCRIPTION=Global Solutions Presentation Platform
CLIENT_SUPPORT_EMAIL=help@globalsolutions.com
CLIENT_SUPPORT_URL=https://help.globalsolutions.com

Docker Compose¶

Add to your .env.local file:

# Acme Corp Branding
CLIENT_NAME=Acme Corp
CLIENT_LOGO=/static/img/clients/acme/logo.png
CLIENT_LOGO_LARGE=/static/img/clients/acme/logo_large.png
CLIENT_PRIMARY_COLOR=#007ACC
CLIENT_DESCRIPTION=Acme Corp Presentation Platform

Then mount your logo files in docker-compose.yml:

services:
  web:
    environment:
      - CLIENT_NAME=${CLIENT_NAME}
      - CLIENT_PRIMARY_COLOR=${CLIENT_PRIMARY_COLOR}
    volumes:
      - ./branding/acme/logo.png:/app/static/img/clients/acme/logo.png:ro
      - ./branding/acme/logo_large.png:/app/static/img/clients/acme/logo_large.png:ro

Azure Container Apps¶

Set environment variables via Azure Portal or CLI:

az containerapp update \
  --name slidefactory-preview \
  --resource-group rg-slidefactory \
  --set-env-vars \
    CLIENT_NAME="Acme Corp" \
    CLIENT_LOGO="/static/img/clients/acme/logo.png" \
    CLIENT_LOGO_LARGE="/static/img/clients/acme/logo_large.png" \
    CLIENT_PRIMARY_COLOR="#007ACC"

Upload logo files via: 1. Build custom Docker image with logos included 2. Mount Azure File Share with logos 3. Use Azure Blob Storage and update paths

Local Development¶

Create .env file in project root:

# .env
CLIENT_NAME=Acme Corp
CLIENT_LOGO=/static/img/clients/acme/logo.png
CLIENT_LOGO_LARGE=/static/img/clients/acme/logo_large.png
CLIENT_PRIMARY_COLOR=#007ACC

Place logo files in static/img/clients/acme/ directory.

Where Branding Appears¶

CLIENT_NAME is used in:¶

✅ Browser tab title
✅ FastAPI documentation title (/docs)
✅ Navigation breadcrumb
✅ Login page header
✅ PWA manifest (app name on mobile home screen)
✅ Email templates (if configured)

CLIENT_LOGO is used in:¶

✅ Navigation bar (top-left)
✅ Chat widget header
✅ Logged-out navigation
✅ Mobile app icon (if PWA installed)

CLIENT_LOGO_LARGE is used in:¶

✅ Login page banner
✅ Welcome/landing pages

CLIENT_PRIMARY_COLOR is used in:¶

✅ Action buttons (Submit, Send, etc.)
✅ Navigation highlights
✅ Links and hover states
✅ Chat widget accent color
✅ PWA theme color (mobile browser chrome)
✅ Favicon background (generated)

Multi-Tenant Setup¶

For serving multiple clients from the same deployment.

Option 1: Subdomain-Based¶

Use different subdomains with environment variable overrides:

# acme.yourdomain.com
CLIENT_NAME=Acme Corp
CLIENT_LOGO=/static/img/clients/acme/logo.png
CLIENT_PRIMARY_COLOR=#007ACC

# globex.yourdomain.com
CLIENT_NAME=Globex Corporation
CLIENT_LOGO=/static/img/clients/globex/logo.png
CLIENT_PRIMARY_COLOR=#2ECC71

Configure at reverse proxy level (nginx, traefik) or use separate container instances.

Nginx Example:

# acme.yourdomain.com
server {
    server_name acme.yourdomain.com;
    location / {
        proxy_pass http://slidefactory-acme:8000;
        proxy_set_header Host $host;
    }
}

# globex.yourdomain.com
server {
    server_name globex.yourdomain.com;
    location / {
        proxy_pass http://slidefactory-globex:8000;
        proxy_set_header Host $host;
    }
}

Option 2: Database-Driven (Future Enhancement)¶

Store branding configurations in database and load based on: - Domain/subdomain - User organization - API key

Note: This requires custom development. Contact your system administrator.

Testing Your Branding¶

Quick Test Checklist¶

After configuring branding, verify these pages:

Login page - Logo and client name appear correctly
Navigation - Logo visible in top-left corner
Account page - Browser title shows client name
API Docs (/docs) - Title shows client name
Chat widget - Logo and colors match brand
Mobile - PWA manifest uses correct theme color

Test Commands¶

# Start local server
./start.sh

# Check environment variables are loaded
python3 -c "from app.config import settings; print(settings.CLIENT_NAME)"

# Verify configuration
curl http://localhost:8080/manifest.json

# Verify branding in HTML
curl http://localhost:8080/ | grep CLIENT_NAME

# Check API docs title
curl http://localhost:8080/docs | grep "<title>"

# Test logo accessibility
curl -I http://localhost:8080/static/img/logo.png

Troubleshooting¶

Logo Not Appearing¶

Symptom: Logo shows as broken image or alt text

Solutions: 1. Verify file exists at specified path 2. Check file permissions (must be readable) 3. Ensure path starts with /static/img/ 4. Verify Docker volume mount (if using containers) 5. Check browser console for 404 errors

# Verify file exists
ls -lh static/img/logo.png

# Check from inside container
docker exec -it slidefactory-web ls -lh /app/static/img/logo.png

# Test file accessibility
curl -I http://localhost:8080/static/img/logo.png

Wrong Color Showing¶

Symptom: Primary color not applied or shows default red

Solutions: 1. Verify hex format includes # prefix 2. Check for typos in hex code (6 characters only) 3. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R) 4. Restart application to reload config

# Verify environment variable
docker-compose exec web env | grep CLIENT_PRIMARY_COLOR

# Or locally
python3 -c "from app.config import settings; print(settings.CLIENT_PRIMARY_COLOR)"

Environment Variables Not Loading¶

Symptom: Still using default branding after configuration

Solutions: 1. Verify .env file is in project root 2. Check .env file permissions (readable) 3. Restart application after changes 4. Verify variables are set in environment

# Check all CLIENT_* variables
env | grep CLIENT_

# For Docker
docker-compose exec web env | grep CLIENT_

# Restart services
docker-compose restart web

Manifest Not Updating¶

Symptom: PWA still shows old theme color on mobile

Solutions: 1. Dynamic manifest is at /manifest.json (not /static/site.webmanifest.json) 2. Update HTML references to use /manifest.json 3. Clear mobile browser cache 4. Uninstall and reinstall PWA

# Test manifest endpoint
curl http://localhost:8080/manifest.json

# Check for correct theme_color
curl http://localhost:8080/manifest.json | grep theme_color

Advanced Customization¶

Custom Fonts¶

Edit /static/css/link_colors.css or create custom CSS:

/* custom-fonts.css */
:root {
  --font-family: "Your Custom Font", system-ui, sans-serif;
}

@font-face {
  font-family: "Your Custom Font";
  src: url("/static/fonts/custom-font.woff2") format("woff2");
  font-weight: normal;
  font-style: normal;
}

Include in templates:

<link href="/static/css/custom-fonts.css" rel="stylesheet">

Additional Brand Colors¶

For more extensive theming, override CSS variables:

/* custom-branding.css */
:root {
  --primary: #your-primary;
  --secondary: #your-secondary;
  --accent: #your-accent;
  --background: #your-background;
  --text: #your-text-color;
}

Include in templates:

<link href="/static/css/custom-branding.css" rel="stylesheet">

Logo Fallbacks¶

The system gracefully handles missing logos: - Falls back to alt text if image fails to load - Uses default logos if paths are invalid - Logs warnings for debugging

Security Considerations¶

Logo File Security¶

✅ Use HTTPS: Always serve logos over HTTPS in production
✅ File size limits: Keep logos under 1MB to prevent abuse
✅ Allowed formats: PNG, SVG only (no executable formats)
✅ Path validation: Paths are restricted to /static/img/ directory
⚠️ User uploads: If allowing user uploads, implement virus scanning

Color Injection Prevention¶

✅ Hex validation: System validates hex color format
✅ CSS escaping: Colors are properly escaped in templates
✅ No JavaScript: Colors are CSS-only (no script injection risk)

Original Sportfive Branding¶

The original Sportfive branding files are preserved in /static/img/branding/ for reference or restoration.

To restore Sportfive branding:

# Set environment variables
CLIENT_NAME="Sportfive Slidefactory"
CLIENT_LOGO="/static/img/branding/sportfive_logo_red.png"
CLIENT_LOGO_LARGE="/static/img/branding/bannerlogo.png"
CLIENT_PRIMARY_COLOR="#ee0000"

Environment Variables - Complete configuration reference
Azure Deployment - Production deployment guide
Branding Guide - Full branding documentation
Whitelabel Quick Start - Quick setup guide

Quick Configuration Check

Use this command to verify your branding configuration:

python3 -c "from app.config import settings; print(f'Name: {settings.CLIENT_NAME}\\nColor: {settings.CLIENT_PRIMARY_COLOR}\\nLogo: {settings.CLIENT_LOGO}')"

Example Branding Configurations

See static/img/branding/ for reference assets including the original Sportfive branding.

Whitelabel & Branding¶

Overview¶

Quick Start¶

Prerequisites¶

Step 1: Place Logo Files¶

Step 2: Set Environment Variables¶

Step 3: Restart & Verify¶

Configuration Reference¶

Environment Variables¶

Logo Specifications¶

Small Logo (CLIENT_LOGO)¶

Large Logo (CLIENT_LOGO_LARGE)¶

Color Configuration¶

Primary Color¶

Additional Colors¶

Deployment Examples¶

Minimal Setup¶

Full Customization¶

Docker Compose¶

Azure Container Apps¶

Local Development¶

Where Branding Appears¶

CLIENT_NAME is used in:¶

CLIENT_LOGO is used in:¶

CLIENT_LOGO_LARGE is used in:¶

CLIENT_PRIMARY_COLOR is used in:¶

Multi-Tenant Setup¶

Option 1: Subdomain-Based¶

Option 2: Database-Driven (Future Enhancement)¶

Testing Your Branding¶

Quick Test Checklist¶

Test Commands¶

Troubleshooting¶

Logo Not Appearing¶

Wrong Color Showing¶

Environment Variables Not Loading¶

Manifest Not Updating¶

Advanced Customization¶

Custom Fonts¶

Additional Brand Colors¶

Logo Fallbacks¶

Security Considerations¶

Logo File Security¶

Color Injection Prevention¶

Original Sportfive Branding¶

Related Documentation¶