Multi-Site Provisioning

Architect and provision multiple isolated chat communities from a single instance using a multi-site capable license.

Overview

Multi-site provisioning enables organizations, agencies, and community platforms to host multiple completely isolated chat tenants on a single deployed JChat instance, single database, and unified Redis real-time bus.

Each site operates as an autonomous community with its own:

Dedicated chat rooms, channels, and direct messages.
Custom branding, site settings, and vanity URLs.
Isolated user memberships, roles, and site permissions.
Independent custom assets (stickers, emojis, and uploads).

Routing Modes: Path vs. Subdomain

JChat supports two tenant routing architectures, configured via the JCHAT_ROUTING_MODE environment variable in .env:

Feature / Consideration	Path-Based Routing (`"path"`)	Subdomain-Based Routing (`"subdomain"`)
URL Structure	`https://example.com/tech/rooms`	`https://tech.example.com/rooms`
Owner Control Panel	`https://example.com/owner`	`https://manage.example.com/`
DNS Configuration	Single `A` / `AAAA` record	Wildcard DNS record (`*.example.com`)
SSL / TLS Certificate	Standard single-domain cert	Wildcard TLS certificate (`*.example.com`)
Cookie Scope	Same-origin path cookies	Strict host-only cookies (zero leakage)
Best For	Fast deployment, single domain	Branded white-label communities

Deep Dive: Routing Implementations

Subdomain mode provides complete visual white-labeling and enhanced browser security via host-only cookie isolation:

1. Environment Configuration

In your .env file, set JCHAT_ROUTING_MODE="subdomain" and specify your root apex domain in JCHAT_DOMAIN:

# Root apex domain for all subdomains
JCHAT_DOMAIN="example.com"
JCHAT_SITE_URL="https://example.com"
JCHAT_ROUTING_MODE="subdomain"

2. Host Classification & Reserved Namespaces

Owner Host: The platform-owner portal is derived automatically as manage.<JCHAT_DOMAIN> (e.g. https://manage.example.com). The subdomain manage is strictly reserved for global platform administration.
Tenant Hosts: Every additional site uses its unique slug as its subdomain (e.g. https://tech.example.com).
Canonical Redirects: Incoming requests containing duplicate path slugs (such as https://tech.example.com/tech/chat) are automatically redirected to canonical bare paths (https://tech.example.com/chat).

When switching between the Owner Control Panel (manage.example.com) and individual site communities, JChat automatically and securely handles session transitions between subdomains while preserving strict host-only cookie isolation for maximum security.

Creating Additional Sites

Platform owners can provision new tenant communities directly from the user interface:

Open the Sites Inventory

Log into the Owner Control Panel and navigate to Sites (/owner/sites).

Click "Create Site"

Click New Site in the top-right corner to open the tenant provisioning modal.

Configure Tenant Parameters

Site Name: Display name for the community (e.g. Tech Innovators).
Site Slug: Unique URL identifier (e.g. tech), used as either the subdomain (tech.example.com) or path prefix (/tech).
Default Language: Primary interface language for this tenant.
Initial Administrator: Assign an existing user or specify a new administrator email.

Automatic Community Provisioning

When submitted, JChat immediately configures the new community:

Initializes default community roles and permissions (Owner, Admin, Moderator, Member).
Assigns full administrative permissions to the designated administrator.
Instantly activates the new community across your cluster without server downtime or restarts.

Reverse Proxy & Wildcard DNS (For Subdomain Mode)

When using subdomain routing, configure your DNS provider and reverse proxy to route all subdomains to your JChat server:

1. Wildcard DNS Record

Add a wildcard A record pointing to your server's public IP:

Type: A
Name: *.example.com (or simply *)
Value: 192.0.2.1
TTL: Auto / 300

2. Caddyfile Configuration (Automatic Wildcard TLS)

Caddy can automatically issue and renew a wildcard Let's Encrypt / ZeroSSL certificate using the DNS-01 ACME challenge (e.g. with the Cloudflare DNS plugin):

*.example.com, example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }

    reverse_proxy 127.0.0.1:3000 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

3. Nginx Configuration

If using Nginx with an existing wildcard certificate:

server {
    listen 443 ssl http2;
    server_name ~^(?<subdomain>.+)\.example.com$;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}