# White-Label Branding Strategy in DeskcommCRM: How to Remove "Deskcomm" from the UI

> Implement white-label branding in DeskcommCRM using environment variables and database settings. Remove 'Deskcomm' at runtime with code-free configuration and automated tests for a seamless user experience.

- Repository: [Rafael Melgaço/DeskcommCRM](https://github.com/melgarafael/DeskcommCRM)
- Tags: how-to-guide
- Published: 2026-09-12

---

**DeskcommCRM implements a configuration-first, code-free branding approach that uses environment variables and database-stored settings to replace the "Deskcomm" name at runtime, enforced by automated tests that scan the codebase for any literal string matches.**

DeskcommCRM (melgarafael/DeskcommCRM) is architected specifically for agencies and resellers who must sell the platform under their own identity. The white-label branding strategy ensures that the original product name never appears in the end-user interface through runtime configuration, tenant-specific database overrides, and strict code-level guards.

## Configuration-First Branding Architecture

The platform separates branding into three distinct layers: installation defaults, per-organization overrides, and admin-controlled global settings. This hierarchy ensures that a single Docker image can serve any reseller without rebuilding.

### Environment-Based Installation Defaults

The foundation of the strategy rests on three environment variables defined in [`lib/env.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/env.ts) (see the comment at approximately line 332): `APP_NAME`, `APP_LOGO_URL`, and `APP_ACCENT_HEX`. These values serve as fallback defaults when no tenant-specific brand exists. By externalizing the brand identity to the environment, the compiled Docker image remains completely generic and reusable across multiple resellers.

### Per-Organization Brand Customization

Each tenant can override installation defaults through the settings UI at `/app/settings/marca`. The interface, implemented in [`app/app/settings/marca/page.tsx`](https://github.com/melgarafael/DeskcommCRM/blob/main/app/app/settings/marca/page.tsx), persists brand values—name, color, and logo—to the `organizations.settings.branding` database table. After authentication, these settings take precedence over environment variables, allowing multi-tenant deployments where each organization maintains a distinct visual identity without affecting others.

### Admin-Level Global Brand Control

For installation-wide branding used on public-facing login screens and system emails, administrators modify settings at `/admin/marca` via [`app/admin/marca/page.tsx`](https://github.com/melgarafael/DeskcommCRM/blob/main/app/admin/marca/page.tsx). Changes persist immediately to the database and take effect without container restarts, ensuring zero-downtime rebranding across the entire instance.

## Code-Level Enforcement Mechanisms

To prevent accidental leakage of the original product name, the codebase implements automated scanning and centralized helper functions that abstract all brand references.

### Automated "Deskcomm" String Detection

The file [`tests/unit/branding.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/branding.test.ts) contains a unit test that executes a recursive grep across the entire source tree—including `app`, `components`, `lib`, `workers`, and `hooks`—searching for the literal string "Deskcomm". The test fails if any occurrence is found, creating a CI/CD gate that prevents developers from hard-coding the original brand into new features or components.

### Brand-Aware Helper Functions

All UI components consume branding through centralized helpers in `lib/branding/*` rather than accessing environment variables directly. The [`lib/branding/icone.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/branding/icone.ts) module provides the `BrandIcon` component that resolves logos from either the database or environment sources, while [`lib/branding/saida.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/branding/saida.ts) exports `marcaDaSaida()` and the `useBrandAccent()` hook for retrieving brand names and CSS hex colors dynamically.

## Runtime Injection Strategy

The brand identity is never compiled into the Docker image; instead, it is injected at runtime from either the database (preferred) or the `.env` file (fallback). This prevents the "Deskcomm" name from leaking after system upgrades, as image replacements do not overwrite stored branding data.

### Email Template Synchronization

Email branding for account verification and password reset flows synchronizes with Supabase templates through [`hostgator-setup-kit/marca-emails.sh`](https://github.com/melgarafael/DeskcommCRM/blob/main/hostgator-setup-kit/marca-emails.sh). This script, invoked automatically by [`install.sh`](https://github.com/melgarafael/DeskcommCRM/blob/main/install.sh) and [`update.sh`](https://github.com/melgarafael/DeskcommCRM/blob/main/update.sh), propagates the `APP_NAME` and `APP_LOGO_URL` environment variables into transactional email layouts at deployment time.

### Documented Exceptions

Certain artefacts intentionally retain the original product name due to legal constraints or operational requirements outside reseller control. According to [`docs/white-label.md`](https://github.com/melgarafael/DeskcommCRM/blob/main/docs/white-label.md), LGPD PDF reports and AI budget alarms specifically exclude white-labeling—these limitations are documented in the sections *"O relatório de LGPD é a única coisa que NÃO leva a sua marca"* and *"O alarme de orçamento de IA"*.

## Implementation Examples

The following patterns demonstrate how to consume branding safely without hard-coded strings:

```typescript
/* Reading the current accent color */
import { useBrandAccent } from '@/lib/branding/saida';
const accent = useBrandAccent();   // returns a CSS hex color

```

```tsx
/* Rendering the brand logo */
import { BrandIcon } from '@/lib/branding/icone';
function Header() {
  return (
    <header className="flex items-center">
      <BrandIcon size={32} />   {/* reads logo from DB or .env */}
      <h1 className="ml-2">{process.env.APP_NAME}</h1>
    </header>
  );
}

```

```typescript
/* Changing the brand via admin UI (React Server Action) */
async function updateBrand(formData: FormData) {
  'use server';
  await fetch('/admin/marca', {
    method: 'POST',
    body: formData,
  });
}

```

```typescript
/* The guard test that prevents "Deskcomm" leaks */
import { execSync } from 'child_process';
test('guarda de white-label (self-host)', () => {
  const result = execSync('pnpm exec grep -R "Deskcomm" .', { encoding: 'utf8' });
  expect(result).toBe('');
});

```

## Summary

- **Environment variables** (`APP_NAME`, `APP_LOGO_URL`, `APP_ACCENT_HEX`) in [`lib/env.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/env.ts) provide installation-wide fallback branding
- **Per-organization branding** persists to `organizations.settings.branding` and overrides defaults via [`app/app/settings/marca/page.tsx`](https://github.com/melgarafael/DeskcommCRM/blob/main/app/app/settings/marca/page.tsx)
- **Admin global branding** controls public login screens through [`app/admin/marca/page.tsx`](https://github.com/melgarafael/DeskcommCRM/blob/main/app/admin/marca/page.tsx) without requiring container restarts
- **Automated enforcement** via [`tests/unit/branding.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/branding.test.ts) greps the entire source tree to block "Deskcomm" literals from being committed
- **UI abstraction** through [`lib/branding/icone.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/branding/icone.ts) and [`lib/branding/saida.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/branding/saida.ts) ensures components never contain hard-coded brand strings
- **Email synchronization** occurs via [`hostgator-setup-kit/marca-emails.sh`](https://github.com/melgarafael/DeskcommCRM/blob/main/hostgator-setup-kit/marca-emails.sh) during installation and update routines
- **Documented exceptions** in [`docs/white-label.md`](https://github.com/melgarafael/DeskcommCRM/blob/main/docs/white-label.md) identify LGPD reports and AI budget alarms as non-configurable artefacts

## Frequently Asked Questions

### How does DeskcommCRM prevent the original brand name from appearing in error messages or UI components?

The repository uses [`tests/unit/branding.test.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/tests/unit/branding.test.ts) to execute a recursive search for the literal string "Deskcomm" across all source directories. If the test detects any occurrences, the CI pipeline fails immediately. Additionally, all UI components must import branding data from `lib/branding/*` helpers rather than defining static strings, ensuring that no hard-coded references survive code review.

### Can I change the brand identity without rebuilding the Docker image?

Yes. Because the brand is injected at runtime from the database or `.env` file, you can update the installation-wide brand via the `/admin/marca` UI or modify environment variables and restart the container. The underlying Docker image remains unchanged, allowing the same build artifact to serve unlimited resellers with distinct identities.

### Where are the brand settings stored for individual organizations?

Per-organization brand values—including custom names, hex color codes, and logo URLs—are stored in the `organizations.settings.branding` table. The application reads these settings after user authentication via [`app/app/settings/marca/page.tsx`](https://github.com/melgarafael/DeskcommCRM/blob/main/app/app/settings/marca/page.tsx), overriding the environment defaults defined in [`lib/env.ts`](https://github.com/melgarafael/DeskcommCRM/blob/main/lib/env.ts) for that specific tenant session.

### Why do some system reports still display the Deskcomm name?

According to [`docs/white-label.md`](https://github.com/melgarafael/DeskcommCRM/blob/main/docs/white-label.md), certain artefacts deliberately retain the original product name due to external constraints. LGPD PDF reports and AI budget alarms are explicitly excluded from white-labeling because they involve legal compliance documentation or operational alerts outside the reseller's control, as noted in the sections *"O relatório de LGPD"* and *"O alarme de orçamento de IA"*.