White Label Configuration

White Label Configuration

This guide covers white-labeling Querri with custom branding, logos, colors, domains, and support contact information.

Overview

Querri supports extensive white-label customization allowing you to present the platform as your own branded solution. This includes:

• Custom logo and favicon
• Brand colors and themes
• Custom domain
• Support email and contact information
• Analytics and tracking
• Help widget customization

Accessing Customization Settings

Customization settings are available at:

https://app.yourcompany.com/settings/customize

Requirements: Admin access

Logo Customization

Application Logo

Via Environment Variable

Set the logo URL in .env-prod:

PUBLIC_LOGO_URL=https://yourcompany.com/assets/logo.png

Restart services to apply:

docker compose restart web-app

Via Database

Update organization branding in MongoDB:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.logo_url": "https://yourcompany.com/assets/logo.png"
    }
  }
)

Logo Specifications

Recommended dimensions:

• Main logo: 200x50px (4:1 aspect ratio)
• Square logo: 100x100px (for favicons)
• Maximum file size: 500KB
• Supported formats: PNG (with transparency), SVG, JPG

Display locations:

• Navigation header (top-left)
• Login page
• Email communications
• Share pages

Favicon

Set custom favicon in .env-prod:

PUBLIC_FAVICON_URL=https://yourcompany.com/assets/favicon.ico

Specifications:

• Format: .ico or .png
• Size: 32x32px or 64x64px
• Transparent background recommended

Dark Mode Logo

Provide alternate logo for dark mode:

PUBLIC_LOGO_DARK_URL=https://yourcompany.com/assets/logo-dark.png

Color Theme Customization

Primary Brand Color

Configure primary brand color in .env-prod:

PUBLIC_BRAND_COLOR=#1e40af

Used for:

• Buttons and CTAs
• Links
• Active states
• Loading indicators
• Chart colors (primary)

Color Palette

For advanced customization, edit the Tailwind configuration:

File: /web-app/tailwind.config.js

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',  // Main brand color
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
        },
      },
    },
  },
}

Rebuild web-app after changes:

docker compose up -d --build web-app

Predefined Themes

Quick theme selection via database:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.theme": "professional"  // professional, vibrant, minimal
    }
  }
)

Available themes:

• professional - Blue/gray palette (default)
• vibrant - Bright, energetic colors
• minimal - Monochrome with accent color
• custom - Full custom color configuration

Custom Domain Setup

DNS Configuration

1. Add DNS Record:

   Type: A
   Name: analytics (or your subdomain)
   Value: YOUR_SERVER_IP
   TTL: 3600

2. Or use CNAME (if behind CDN):

   Type: CNAME
   Name: analytics
   Value: your-server.cloudprovider.com
   TTL: 3600

Update Environment Configuration

Update .env-prod with your custom domain:

# Custom domain
PUBLIC_BASE_URL="https://analytics.yourcompany.com"
PUBLIC_DOMAIN="https://analytics.yourcompany.com"
COOKIE_DOMAIN=analytics.yourcompany.com

# Update WorkOS redirect
WORKOS_REDIRECT_URI=https://analytics.yourcompany.com/hub/auth/callback

SSL/TLS Certificate

Option 1: Let’s Encrypt (Automated)

Update Traefik configuration:

File: /traefik/traefik.yml

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: letsencrypt

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@yourcompany.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

Update docker-compose.yml:

reverse-proxy:
  volumes:
    - "./letsencrypt:/letsencrypt"
  ports:
    - "80:80"
    - "443:443"

Restart Traefik:

docker compose restart reverse-proxy

Option 2: Custom Certificate

Place certificate files in /traefik/certs/:

mkdir -p traefik/certs
# Copy your certificate files
cp yourcompany.com.crt traefik/certs/
cp yourcompany.com.key traefik/certs/

Update Traefik configuration:

File: /traefik/dynamic.yml

tls:
  certificates:
    - certFile: /traefik_config/certs/yourcompany.com.crt
      keyFile: /traefik_config/certs/yourcompany.com.key

Verify Custom Domain

# Test DNS resolution
dig analytics.yourcompany.com

# Test HTTPS
curl -I https://analytics.yourcompany.com

# Check certificate
openssl s_client -connect analytics.yourcompany.com:443 -servername analytics.yourcompany.com

Support Contact Configuration

Support Email

Set support email in .env-prod:

PUBLIC_SUPPORT_EMAIL=support@yourcompany.com

Displayed in:

• Help menus
• Error messages
• Footer
• Email communications

Support Links

Configure help and documentation links:

PUBLIC_DOCS_URL=https://docs.yourcompany.com
PUBLIC_STATUS_URL=https://status.yourcompany.com
PUBLIC_SUPPORT_URL=https://support.yourcompany.com

Update in database for dynamic control:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.support": {
        email: "support@yourcompany.com",
        docs_url: "https://docs.yourcompany.com",
        status_url: "https://status.yourcompany.com",
        support_url: "https://support.yourcompany.com",
        phone: "+1-555-0123"
      }
    }
  }
)

Analytics Configuration

Enable/Disable Analytics

Control analytics tracking in .env-prod:

PUBLIC_ENABLE_ANALYTICS=true

Values:

• true - Enable all analytics
• false - Disable analytics tracking

Segment Analytics

Configure Segment for usage analytics:

SEGMENT_TOKEN=your_segment_write_key

Tracks:

• Page views
• Feature usage
• User actions
• Error events

Google Analytics

Add Google Analytics in .env-prod:

PUBLIC_GA_ID=G-XXXXXXXXXX

Or update via database:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.analytics": {
        google_analytics_id: "G-XXXXXXXXXX",
        segment_write_key: "your_key"
      }
    }
  }
)

Privacy-Compliant Analytics

For GDPR/CCPA compliance, use privacy-focused analytics:

PUBLIC_ANALYTICS_MODE=privacy  # full, privacy, none

Privacy mode:

• No IP address tracking
• No personal data collection
• Anonymized user IDs
• Cookie consent required

Help Widget

Gleap Integration

Gleap provides in-app support widget with bug reporting and feedback.

Configure in .env-prod:

PUBLIC_GLEAP_API_KEY=your_gleap_api_key

Features enabled:

• In-app chat
• Bug reporting with screenshots
• Feature requests
• User feedback surveys

Intercom (Alternative)

PUBLIC_INTERCOM_APP_ID=your_intercom_app_id

Custom Help Widget

Disable built-in widgets and add custom:

PUBLIC_HELP_WIDGET_ENABLED=false
PUBLIC_CUSTOM_HELP_WIDGET_URL=https://yourcompany.com/widget.js

Email Branding

Email Templates

Customize transactional email templates:

Location: /server-api/templates/emails/

Edit templates:

• invitation.html - User invitation emails
• notification.html - System notifications
• share.html - Project share notifications
• report.html - Scheduled report emails

Email Sender

Configure sender information:

PUBLIC_EMAIL_FROM_NAME="Your Company Analytics"
PUBLIC_EMAIL_FROM_ADDRESS=noreply@yourcompany.com

Update SendGrid sender:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.email": {
        from_name: "Your Company Analytics",
        from_address: "noreply@yourcompany.com",
        reply_to: "support@yourcompany.com"
      }
    }
  }
)

Email Footer

Customize email footer:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.email.footer": {
        company_name: "Your Company Inc.",
        address: "123 Main St, City, ST 12345",
        unsubscribe_text: "Manage your email preferences"
      }
    }
  }
)

Application Name

Product Name

Change the application name throughout the UI:

PUBLIC_APP_NAME="Your Analytics Platform"
PUBLIC_APP_SHORT_NAME="YAP"

Displayed in:

• Browser title
• Navigation
• Email subject lines
• Mobile app name

Meta Tags

Update meta tags for SEO and social sharing:

PUBLIC_META_TITLE="Your Analytics Platform"
PUBLIC_META_DESCRIPTION="Advanced analytics and data visualization for your organization"
PUBLIC_META_IMAGE=https://yourcompany.com/assets/social-preview.png

Login Page Customization

Custom Background

Set login page background:

PUBLIC_LOGIN_BG_IMAGE=https://yourcompany.com/assets/login-bg.jpg
PUBLIC_LOGIN_BG_COLOR=#f0f4f8

Login Message

Display custom message on login page:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.login": {
        welcome_message: "Welcome to Your Analytics Platform",
        subtitle: "Data-driven insights for your organization",
        show_demo_link: false
      }
    }
  }
)

Footer Customization

Company Information

Update footer information:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.footer": {
        company_name: "Your Company Inc.",
        copyright_year: 2024,
        links: [
          {title: "Privacy Policy", url: "https://yourcompany.com/privacy"},
          {title: "Terms of Service", url: "https://yourcompany.com/terms"},
          {title: "Documentation", url: "https://docs.yourcompany.com"}
        ]
      }
    }
  }
)

Hide Powered By

Remove “Powered by Querri” footer:

PUBLIC_HIDE_POWERED_BY=true

White Label Checklist

Before going live with white-label deployment:

Visual Branding

• Logo uploaded and displaying correctly
• Favicon set
• Brand colors configured
• Dark mode logo (if using dark mode)
• Login page customized

Domain & SSL

• DNS records configured
• SSL certificate installed
• HTTPS working correctly
• Cookie domain updated
• WorkOS redirect URI updated

Contact Information

• Support email set
• Documentation URL configured
• Status page URL (if applicable)
• Phone number (if applicable)
• Company address (for emails)

Email Configuration

• Email sender name updated
• Email templates customized
• Email footer configured
• SendGrid verified sender

Analytics & Tracking

• Analytics enabled/disabled as desired
• Analytics IDs configured
• Privacy mode set appropriately
• Cookie consent configured

Application Text

• Application name updated
• Meta tags configured
• Footer links updated
• “Powered by” hidden (if desired)

Help & Support

• Help widget configured
• Support links working
• Documentation accessible

Testing White Label Configuration

Visual Testing Checklist

1. Logo display:

   - [ ] Header (logged in)
   - [ ] Login page
   - [ ] Email templates
   - [ ] Share pages
   - [ ] Mobile responsive

2. Colors:

   - [ ] Buttons match brand
   - [ ] Links match brand
   - [ ] Charts use brand colors
   - [ ] Dark mode (if applicable)

3. Domain:

   - [ ] Custom domain resolves
   - [ ] HTTPS certificate valid
   - [ ] Redirects working
   - [ ] Cookies set correctly

Automated Testing

Test white-label configuration:

# Test logo URLs accessible
curl -I $PUBLIC_LOGO_URL
curl -I $PUBLIC_FAVICON_URL

# Test custom domain
curl -I https://analytics.yourcompany.com

# Verify environment variables loaded
docker compose exec web-app env | grep PUBLIC_

Troubleshooting

Logo Not Displaying

1. Verify URL is publicly accessible:

   curl -I https://yourcompany.com/assets/logo.png

2. Check CORS headers if hosted externally:

   Access-Control-Allow-Origin: *

3. Verify image format is supported (PNG, SVG, JPG)

4. Clear browser cache and reload

Custom Domain Not Working

1. Verify DNS propagation:

   dig analytics.yourcompany.com
   nslookup analytics.yourcompany.com

2. Check SSL certificate:

   openssl s_client -connect analytics.yourcompany.com:443

3. Verify environment variables updated:

   docker compose exec web-app env | grep PUBLIC_DOMAIN

4. Restart all services:

   docker compose restart

Colors Not Applying

1. Check environment variable syntax:

   PUBLIC_BRAND_COLOR=#1e40af  # Include # symbol

2. Clear browser cache

3. Rebuild web-app if Tailwind config changed:

   docker compose up -d --build web-app

Email Branding Issues

1. Verify SendGrid sender authentication

2. Check email template syntax (valid HTML)

3. Test email send:

   docker compose exec server-api python -c "
   from api.utils.email import send_email
   send_email('test@example.com', 'Test', '<html>Test</html>')
   "

Advanced Customization

Custom CSS

Add custom CSS for advanced styling:

File: /web-app/src/styles/custom.css

:root {
  --brand-primary: #1e40af;
  --brand-secondary: #64748b;
  --brand-accent: #f59e0b;
}

.btn-primary {
  background-color: var(--brand-primary);
}

Import in /web-app/src/routes/+layout.svelte:

<script>
  import '../styles/custom.css';
</script>

Custom Fonts

Add custom fonts in .env-prod:

PUBLIC_FONT_FAMILY="'Inter', sans-serif"
PUBLIC_FONT_URL=https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap

Custom JavaScript

Inject custom JavaScript (analytics, etc.):

PUBLIC_CUSTOM_SCRIPT_URL=https://yourcompany.com/scripts/custom.js

Best Practices

1. Consistent branding - Use same logos/colors across all touchpoints
2. Test on multiple devices - Mobile, tablet, desktop
3. Performance - Optimize logo file sizes
4. Accessibility - Ensure color contrast meets WCAG standards
5. Documentation - Document all customizations for team reference
6. Backups - Save original logos and assets
7. Version control - Track branding changes over time

Next Steps

• Organization Settings - Configure organization defaults
• Environment Configuration - Set up environment variables
• Installation & Deployment - Deploy with custom branding