ZChat ZChat 2.0 Self-Hosted Live Chat

Installation Guide

Complete walkthrough

Install ZChat on your own infrastructure in under 30 minutes.

This guide covers everything from prerequisites and database setup through widget embedding and production hardening. Follow the steps in order for a clean deployment on Windows (IIS or Kestrel), Linux (Nginx), or Docker.

1. Prerequisites 2. Download 3. Database 4. Configure 5. Start 6. Widget 7. License 8. Production 9. Docker 10. AI Setup

What you will deploy

The ZChat package includes:

Self-hosted server

.NET 8 ASP.NET Core application with SignalR real-time transport

Web dashboard

Blazor WebAssembly admin console for agents, settings, and analytics

Embeddable chat widget

Lightweight script (under 13 KB gzipped) for any website

Desktop agent console

Native WinUI 3 Windows app with system tray and notifications

Database schema

SQL Server install script for tables, indexes, and seed data

1

Prerequisites

Install these before proceeding

Runtime

.NET 8 Runtime

Download and install the ASP.NET Core Runtime 8.0 (or later) from dotnet.microsoft.com. On Windows with IIS, install the ASP.NET Core Hosting Bundle instead, which includes the runtime plus the IIS module.
Verify installation: dotnet --list-runtimes

Database

SQL Server

SQL Server 2014 or later (Express, Standard, or Enterprise). SQL Server Express is free and works well for most deployments.
Download: SQL Server Downloads
Azure SQL Database is also supported for cloud deployments.

Operating system

Windows or Linux

Windows: Windows Server 2016+ or Windows 10+ for local testing.
Linux: Ubuntu 20.04+, Debian 11+, RHEL 8+, or any distro with .NET 8 support.
Docker: Any host with Docker Engine. See the Docker section below.

Hardware

Minimum specs

x64 processor, 1 GB RAM minimum (2 GB recommended), 500 MB disk space for the application.
Virtual machines and cloud VMs (Azure, AWS, DigitalOcean, etc.) are fully supported.
2

Download and extract

Get the ZChat installation package

Download the ZChat installation package from the downloads page and extract it to a folder on your server.

# Example: extract to C:\inetpub\ZChat

Expand-Archive zchat-install.zip -DestinationPath C:\inetpub\ZChat

Package contents

Web/                # Server application
   appsettings.json  # Configuration
   ZChat.lic         # License file
   install/         # DB install script
   wwwroot/         # Dashboard + widget
Console/             # Desktop agent (Windows)
Document/            # Documentation
READ_ME.txt          # Quick start
3

Create the database

Set up SQL Server tables and schema

Create a blank database in SQL Server, then run the install script to create all required tables.

-- Step A: Create the database

CREATE DATABASE ZChat;
GO

-- Step B: Run the schema script

USE ZChat;
GO
-- Run: Web\install\ZCHAT-APP-DB.sql

Using SQL Server Management Studio?

Open SSMS, connect to your SQL Server instance, create a new database named "ZChat", then open and execute Web\install\ZCHAT-APP-DB.sql against it. The script uses IF NOT EXISTS checks so it is safe to run multiple times.

4

Configure the application

Edit appsettings.json with your environment details

Open Web\appsettings.json and update the settings below. A reference copy is also available at appsettings.example.json.

appsettings.json 
{
  "ConnectionStrings": {
    "ZChat": "Server=YOUR_SERVER;Database=ZChat;
              Trusted_Connection=true;
              TrustServerCertificate=true"
  },
  "Jwt": {
    "SecretKey": "CHANGE-THIS-TO-A-RANDOM-STRING-MIN-32-CHARS",
    "Issuer": "ZChat",
    "Audience": "ZChat",
    "ExpirationMinutes": 480
  },
  "AllowedHosts": "*"
}

Connection string

Replace YOUR_SERVER with your SQL Server instance name:

  • . or (local) for a default local instance
  • .\SQLEXPRESS for SQL Server Express
  • 192.168.1.50 for a remote server
  • myserver.database.windows.net for Azure SQL

For SQL authentication, use:
Server=...;Database=ZChat;User Id=sa;Password=YOUR_PASSWORD;

JWT secret key

The JWT secret key secures authentication tokens for the dashboard and agent console. Requirements:

  • At least 32 characters long
  • Random, unique per deployment
  • Never use the default value in production

Generate one with PowerShell:
[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Max 256 }))

5

Start the server

Launch ZChat and verify it works

Quick start (Kestrel)

The simplest way to verify your installation. Run the server directly using the built-in Kestrel web server:

cd Web
dotnet ZChat.Web.dll --urls "http://localhost:5000"

Open your browser to http://localhost:5000/dashboard to access the web dashboard.

Default login credentials

Username: admin  Password: admin123

Change the default password immediately after first login.

Quick smoke test

If you have SQL Server Express locally and want the fastest possible test, use the included helper script:

# Windows batch file
run-local.cmd

# PowerShell with custom DB/port
.\run-local.ps1 -Database zchatdemo -Port 5050

This starts ZChat at http://127.0.0.1:5050/dashboard using the local SQL Express instance.

Verify the health endpoint

Navigate to http://localhost:5000/api/health in your browser. You should see a JSON response with "status": "healthy".

6

Add the chat widget to your website

Embed ZChat on any web page with a script tag

Add the following code before the closing </body> tag of every page where you want the chat widget to appear. The widget works on any website technology: HTML, PHP, WordPress, React, Shopify, ASP.NET, etc.

your-website.html 
<script src="https://YOUR-ZCHAT-SERVER/widget/zchat.iife.js"></script>
<script>
  ZChat.init({
    serverUrl: 'https://YOUR-ZCHAT-SERVER',
    siteId: 'default'
  });
</script>

Replace YOUR-ZCHAT-SERVER with the URL where ZChat is deployed (e.g. https://chat.yourcompany.com). The widget automatically shows a launcher button in the bottom-right corner of the page.

Customization

Colors, position, greeting text, and pre-chat form fields can be configured from the web dashboard under Widget Builder.

Dark mode

The widget includes built-in dark mode support that respects the visitor's system preference or can be set explicitly.

Shadow DOM

Widget styles are isolated using Shadow DOM so they will not conflict with your existing website CSS.

7

Activate your license

Free for localhost, one-time purchase for production domains

Free evaluation

Localhost deployments are free

ZChat runs on localhost with unlimited agents and no time limit using the included license file. No purchase needed for development, testing, or internal demos.

Production deployment

One-time purchase, perpetual license

When you are ready to go live on a production domain, purchase a license from the pricing page. Download the .lic file from the client center, place it in the Web/ directory as ZChat.lic, and restart the server.

# Place the license file in the Web root folder

copy ZChat.lic  C:\inetpub\ZChat\Web\ZChat.lic

# Then restart the ZChat server to pick up the new license

Free

Localhost, unlimited agents, no time limit

$299

Professional: per domain, up to 10 agents

$599

Enterprise: per domain, unlimited agents

8

Production deployment

Host behind IIS (Windows) or Nginx (Linux) with HTTPS

Windows + IIS

  1. 1. Install the ASP.NET Core Hosting Bundle for .NET 8.
  2. 2. Open IIS Manager, right-click Sites and choose Add Website.
  3. 3. Set the physical path to the Web/ folder from the ZChat package.
  4. 4. Bind to your domain (e.g. chat.yourcompany.com) on port 443 with an SSL certificate.
  5. 5. Ensure the Application Pool is set to No Managed Code (since .NET 8 uses its own runtime).
  6. 6. Grant the App Pool identity read/write access to the Web/App_Data folder.
  7. 7. Browse to https://chat.yourcompany.com/dashboard to verify.

Linux + Nginx

# /etc/nginx/sites-available/zchat

server {
    listen 443 ssl;
    server_name chat.yourcompany.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For
                         $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# systemd service unit

[Unit]
Description=ZChat Server
After=network.target

[Service]
WorkingDirectory=/opt/zchat/Web
ExecStart=/usr/bin/dotnet ZChat.Web.dll \
    --urls "http://127.0.0.1:5000"
Restart=always
RestartSec=10
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

Production checklist

Use HTTPS with a valid SSL certificate
Change the default admin password
Set a unique JWT SecretKey (32+ chars)
Use SQL authentication (not Trusted) if remote DB
Delete the install/ folder after setup
Enable WebSocket support in your reverse proxy
9

Docker deployment (optional)

Container-based hosting for teams that prefer it

ZChat includes a multi-stage Dockerfile that builds the server, dashboard, and widget into a single optimized container image.

# Build the image

docker build -t zchat -f src/ZChat.Web/Dockerfile .

# Run the container

docker run -d -p 5000:5000 \
  -e ConnectionStrings__ZChat="Server=host.docker.internal;\
     Database=ZChat;User Id=sa;Password=YOUR_PASSWORD;\
     TrustServerCertificate=true" \
  -e Jwt__SecretKey="your-strong-secret-key-min-32-chars" \
  zchat

Non-root user

The container runs as a non-root user for better security.

Health check

Built-in Docker HEALTHCHECK pings /api/health every 30 seconds.

Environment config

All appsettings can be overridden with environment variables using __ as the section separator.

10

AI chatbot setup (optional)

Connect Ollama, OpenAI, or Anthropic

ZChat supports bring-your-own AI with no surcharge. Configure the chatbot from the web dashboard under Settings > Chatbot, or directly in appsettings.json:

Ollama (local, private)

"Chatbot": {
  "Enabled": true,
  "Provider": "ollama",
  "ApiEndpoint":
    "http://localhost:11434",
  "Model": "llama3"
}

OpenAI (cloud)

"Chatbot": {
  "Enabled": true,
  "Provider": "openai",
  "ApiKey": "sk-...",
  "Model": "gpt-4o"
}

Anthropic (cloud)

"Chatbot": {
  "Enabled": true,
  "Provider": "anthropic",
  "ApiKey": "sk-ant-...",
  "Model": "claude-sonnet-4-20250514"
}

How AI handoff works

When enabled, the AI chatbot greets visitors, answers common questions, and qualifies conversations. If the visitor asks for a human agent or the AI detects it cannot resolve the issue, ZChat automatically hands the conversation to a live operator with the full chat context already attached.

Desktop agent console

Set up the native Windows agent app for your support team.

The Console/ folder in the installation package contains the WinUI 3 desktop agent application. Distribute it to agent machines for a faster, notification-driven support workflow outside the browser.

Server URL: Point to your ZChat server (e.g. https://chat.yourcompany.com)
Login: Use the same agent credentials as the web dashboard
Requirement: Windows 10 version 1809 or later

Features

System tray presence, native notifications, multi-tab chat sessions, visitor context panel, keyboard shortcuts, and real-time visitor monitoring.

Connection

Connects to ZChat via SignalR WebSocket with JWT authentication. Works through firewalls and proxies.

Need help?

Get installation assistance from the ZChat team.

If you run into issues during deployment, open a support ticket with your environment details (OS, SQL Server version, hosting method, and error messages) for the fastest resolution.

Open Support Ticket Installation Service FAQs

Related documentation

System Requirements REST API Reference API Demo Setup Widget Demo Gallery
Owned customer support software

Deploy live chat on your own terms, not on someone else's pricing model.

ZChat gives you the installable server, web dashboard, website widget, and desktop agent tools in one self-hosted product you buy once and keep. Run it on infrastructure you trust and connect AI only if and how you want it.

Download ZChat See Product Demo

Deployment

Install on Windows or Linux, behind IIS or Nginx, in a VM, or in Docker if that fits your stack.

Commercial model

One-time purchase, perpetual license, and no monthly per-agent bill attached to growth.

AI Flexibility

Use Ollama locally or connect OpenAI and Anthropic with your own provider accounts.