How-to guide

How to upgrade self-hosted live chat safely

A hosted chat tool updates itself, whether you are ready or not. A self-hosted one updates when you decide. This guide shows how to upgrade a DChat server, ASP.NET Core edition, on Windows, Linux or Docker, with a way back if something goes wrong.

Before you start

  1. Read the upgrade notes. The download contains READ_ME.txt. It has one “read this first” section for each release. Read every section between the version you run and the version you are installing. The what's new page lists the changes in plain language.
  2. Take a backup. Back up the database, and copy the whole Web folder to a safe place. The backup and restore guide has the commands.
  3. Pick a quiet time. The chat widget is offline while the server is stopped, usually for a few minutes.

What to keep and what to replace

Keep Replace
Web\appsettings.json
Web\dchat.lic, if you have a licence
Web\App_Data\
Your database
Every other file and folder in Web, with the files from the new download

App_Data holds chat attachments, agent avatars, AI knowledge files, logs and the keys created on first run. If it is replaced, attachments are lost and everyone has to sign in again.

Upgrade on Windows with IIS

  1. Stop the site's application pool in IIS Manager. If DChat runs as a Windows service, stop the service.
  2. Copy the Web folder to a backup location, if you have not done so already.
  3. Unpack the new download to a temporary folder.
  4. Copy the new Web files over the old ones, leaving appsettings.json, dchat.lic and App_Data as they are.
  5. Start the application pool or the service.

Upgrade on Linux

The steps are the same. Stop the service that runs DChat, replace the files in the Web folder while keeping the three items above, and start the service again. Nginx does not need a change unless the upgrade notes say so.

Upgrade in Docker

Unpack the new download over your Compose folder, keeping your .env file, then rebuild and restart:

docker compose up -d --build

App_Data and the database live on named volumes, so they survive a rebuild and a recreated container. Do not run docker compose down -v: the -v switch deletes those volumes and everything in them.

What happens at the first start

The server checks the database when it starts and creates any tables and columns the new version needs. Existing data is left alone. Recent releases have needed no database script: the 2.0.9 to 2.0.10 upgrade, for example, needed no script and no configuration change. On a large database the first start can take longer than usual, because new indexes are built once.

New features usually arrive switched off or empty, so the server behaves as before until you turn them on. Where a release does change behaviour, the upgrade notes say so. Read them for your release.

Check the result

  • Open /api/health on your server. It should answer without an error.
  • Sign in to the dashboard and confirm the version number on the Settings page.
  • Open your website, start a chat from the widget, and answer it as an agent.
  • Open an old conversation and download an attachment.
  • If you use the AI agent, ask it one question it should know.
  • If you have a paid licence, check that the paid features are still on.

If something goes wrong: roll back

  1. Stop the server.
  2. Restore the database backup you took before the upgrade.
  3. Put back the copy of the old Web folder.
  4. Start the server and run the checks above.

Restore the database as well as the files. The new version may have added tables and columns, and the old version was not written with them in mind. Conversations that arrived after the backup are lost in a rollback, which is one more reason to upgrade at a quiet time and to check the result straight away.

Test first, if you can

The safest upgrade is one you have already done once. Restore last night's backup on a test machine, install the new version there, and run the checks. Live chat needs no licence, so a test server on another host name runs with the Community features at no cost.

Common questions

Do I have to upgrade when a new version comes out?

No. A self-hosted DChat server changes only when you install a new version. You choose the day, and you can test the new version on a copy first. Security fixes are a good reason not to wait long.

Which files must I keep when I upgrade?

Keep Web\appsettings.json, your licence file if you have one, and the Web\App_Data folder. Replace everything else in the Web folder with the files from the new download.

Does an upgrade need a database script?

Recent releases have not needed one. For example, the 2.0.9 to 2.0.10 upgrade creates its new tables and columns when the server first starts and leaves existing data alone. Always check the upgrade section of READ_ME.txt for the release you are installing.

How do I roll back a DChat upgrade?

Stop the server, restore the database backup you took before the upgrade, put back the copy of the old Web folder, and start the server. This is why the backup comes first.

Self-hosted customer support software

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

DChat gives you the installable server, web dashboard, website widget, and desktop agent tools in one self-hosted product, with live chat free to run, and an AI agent that answers, acts with the approvals you set and hands off to your team when you want one. Run it on infrastructure you trust, on the model you choose.

Deployment

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

Commercial model

Live chat is free with unlimited agents. Premium, with the AI agent, is billed per agent per month, never per conversation.

AI Flexibility

Run the AI agent on a local Ollama model, or connect OpenAI and Anthropic with your own provider accounts.