Before you start
- 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.
- 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.
- 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
- Stop the site's application pool in IIS Manager. If DChat runs as a Windows service, stop the service.
- Copy the
Web folder to a backup location, if you have not done so already.
- Unpack the new download to a temporary folder.
- Copy the new
Web files over the old ones, leaving appsettings.json, dchat.lic and App_Data as they are.
- 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
- Stop the server.
- Restore the database backup you took before the upgrade.
- Put back the copy of the old
Web folder.
- 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.