Custom Branding

This guide explains how to apply your own logos and brand name to the Zynomi CTMS platform using Docker volume mounts and environment variables. No image rebuild is required.

How It Works

The Zynexa container mounts a host folder into /app/public/brand/ (read-only). Files placed in this folder become available at the /brand/ URL path. The existing baked-in assets under /i/zynomi/, /i/hb/, etc. remain untouched.

Host: ./zynexa-public/       →  Container: /app/public/brand/  (read-only)

Two environment variables tell the app where to find the logo files:

Variable	Purpose	Example
NEXT_PUBLIC_LOGO_PREFIX	Path prefix (without extension)	/brand/logo
NEXT_PUBLIC_LOGO_EXT	File extension	svg
NEXT_PUBLIC_BRAND_NAME	Display name (sidebar, title bar)	Acme Pharma

Required Logo Files

The app expects 4 logo files following a strict naming convention:

File	Usage
{prefix}.{ext}	Main logo — light / default
{prefix}-dark.{ext}	Main logo — dark mode
{prefix}-mark.{ext}	Icon mark — light / default
{prefix}-mark-dark.{ext}	Icon mark — dark mode

Example: Zynomi Logos

The default Zynomi logo set uses SVG format with the prefix /i/zynomi/logo:

public/i/zynomi/
├── logo.svg              # Main logo (light)
├── logo-dark.svg         # Main logo (dark)
├── logo-mark.svg         # Icon mark (light)
└── logo-mark-dark.svg    # Icon mark (dark)

Corresponding environment variables:

NEXT_PUBLIC_LOGO_PREFIX=/i/zynomi/logo
NEXT_PUBLIC_LOGO_EXT=svg

Step-by-Step: Apply Custom Branding

1. Create the host folder

On the deployment server:

mkdir -p ./zynexa-public

2. Place your logo files

Copy your 4 logo files into the folder, following the naming convention. For example, if your prefix is logo and extension is png:

ls ./zynexa-public/
# logo.png            (main logo - light)
# logo-dark.png       (main logo - dark)
# logo-mark.png       (icon mark - light)
# logo-mark-dark.png  (icon mark - dark)

3. Set environment variables

Add to your .env file:

# Custom branding
NEXT_PUBLIC_LOGO_PREFIX=/brand/logo
NEXT_PUBLIC_LOGO_EXT=png
NEXT_PUBLIC_BRAND_NAME=Acme Pharma

The prefix /brand/logo maps to the files inside ./zynexa-public/ because the volume mount maps:

./zynexa-public/logo.png  →  /app/public/brand/logo.png  →  URL: /brand/logo.png

4. Restart Zynexa

docker compose up -d zynexa

The app will now serve your custom logos and display your brand name. No rebuild needed.

Docker Compose Reference

The volume mount in docker-compose.yml:

zynexa:
  volumes:
    - ./zynexa-public:/app/public/brand:ro

The :ro flag makes the mount read-only inside the container.

Resetting to Default

To revert to the default Zynomi branding, remove the environment variable overrides from .env:

# Remove or comment out:
# NEXT_PUBLIC_LOGO_PREFIX=/brand/logo
# NEXT_PUBLIC_LOGO_EXT=png
# NEXT_PUBLIC_BRAND_NAME=Acme Pharma

Then restart:

docker compose up -d zynexa

The app falls back to the built-in defaults (/i/zynomi/logo with svg extension).

Troubleshooting

Symptom	Cause	Fix
Logo not showing	File naming mismatch	Ensure all 4 files follow {prefix}.{ext}, {prefix}-dark.{ext}, {prefix}-mark.{ext}, {prefix}-mark-dark.{ext}
404 on logo URL	Prefix doesn't start with /brand/	The volume mounts to /brand/ — prefix must start with /brand/
Old logo still appears	Browser cache	Hard refresh (Ctrl+Shift+R) or clear cache
Permission denied	File ownership	Ensure files are readable: chmod 644 ./zynexa-public/*