Whitelabeling Your Deployment

All of the platform's branding is controlled by one file — frontend/whitelabel.json. Edit it to rebrand the console (name, subtitle, logo, favicon, copyright, social-preview metadata) without touching application code. There's no database change and no admin screen; branding is a build-time concern.

The config file

frontend/whitelabel.json holds a flat set of fields. The required ones are appName (sidebar header, <title>, social titles), appSubtitle (under the app name), appDescription (the meta/OG/Twitter description), logoPath (sidebar and login logo, resolved from frontend/public/), and copyrightNotice (sidebar footer). Optional ones are tabDescription (renders the tab as {appName} - {tabDescription}), faviconPath, and ogImageUrl / twitterImageUrl.

Static assets

Logo and favicon files go in frontend/public/ (served at the root path). A square PNG/SVG logo of at least 128×128 works best — note the sidebar applies CSS filters (grayscale, contrast, blend), so pick a logo that survives them or adjust the styles in Layout.tsx. Social images (ogImageUrl, twitterImageUrl) must be absolute URLs — crawlers fetch them directly and can't resolve relative paths; twitterImageUrl falls back to ogImageUrl, and leaving both empty simply omits the image tags.

How it's applied — and why a rebuild is needed

The config is consumed at build time, in two ways. A Vite plugin injects the static <title>, favicon, description, and Open Graph / Twitter tags into index.html, so social crawlers (which don't run JavaScript) get correct metadata. Separately, React components (Layout.tsx, the auth pages) import whitelabel.json directly, and Vite bundles the values into the JS — no runtime file read or API call.

Because everything is baked in at build, a running container won't reflect edits until the frontend is rebuilt:

docker compose up -d --build frontend    # Docker
npm run dev                              # local — picks up changes on restart

The version shown in the sidebar footer is not part of whitelabel config — it comes from the VITE_APP_VERSION build arg (see Versioning & Cutting a Release).