DS Server

Upgrading

Topic

An installation of DS Server is a folder of files, so an upgrade replaces that folder with the matching folder of a newer archive, or a container with one from a newer image. What has to survive the upgrade is small: the admin database with the password and the security profiles, your changes to the configuration files, certificates and plugins. A major version can also need new runtimes and new client packages.

Read on before you move a server to a new update or major version: what to back up, the steps for a server and for a container, and the steps specific to the versions 3.0, 4.0 and 5.0.

Before You Start

  • Find the version you run. The footer of every page of the admin portal shows it, for example "DS Server version 5.0.2". The CHANGELOG.md in the DS Server folder lists the releases up to the installed one.
  • Get the new archive. The current release is 5.0.2, in the archive DS Server 5.0.2.zip. Updates and new major versions are included while the license period of your DS Server license runs; download the new archive from your Text Control account.
  • Read the What's New pages of every version between yours and the target, in particular their Upgrading sections: Version 5.0, Version 4.0 and Version 3.0.
  • Check the requirements. A major version can need a newer .NET runtime. See Requirements.

What to Keep

KeepWhy
Admin.dbThe admin password, the security profiles and the OAuth setting. Without it, the new installation starts with the password admin, no profiles and OAuth disabled.
Your changes to appsettings.json and hostsettings.jsonPorts, Kestrel endpoints, log settings and the path of the admin database
Your changes to web.configSettings for IIS
Certificate filesUsed by Kestrel endpoints, see HTTPS
The subfolders of PluginsYour plugins, rebuilt for the new version when needed
The logs folderOptional, for the history of the old installation

If you moved Admin.db or the logs out of the DS Server folder with absolute paths, as Configuration describes, they stay where they are and only the configuration has to point to them again.

Upgrade a Server

  1. Install the runtimes of the new version, if they changed, before you stop the old one. See Requirements.
  2. Stop DS Server: sudo systemctl stop dsserver.service for a systemd service, Stop-Service -Name DSServer for a Windows service, or stop the site in IIS Manager.
  3. Back up the DS Server folder, including Admin.db.
  4. Extract the build folder of the new archive, core or classic, to a new folder.
  5. Copy what you keep from the old folder into the new one: Admin.db, the certificates and the plugin subfolders of Plugins. Apply your changes to appsettings.json, hostsettings.json and web.config to the new files instead of copying the old files over them, so that settings of the new version are kept.
  6. Replace the old folder with the new one, or point the service, the systemd unit or the IIS site to the new folder.
  7. Start DS Server and open the admin portal. Check the version in the footer, the license on the Licensing page, and that the security profiles are listed.
  8. Update and test your applications with the client packages of the new version.

Upgrade a Container

  • Official image. Remove the container and start a new one from the new tag, for example txtextcontrol/dsserver-core:5.0.1, with the same volumes and environment variables. If the container keeps Admin.db on a volume, as Installing with Official Image from Docker Hub describes, the new container uses it. If it doesn't, copy the database out before you remove the container, and copy it into the new container before you configure anything:

    docker cp dsserver:/app/Admin.db ./Admin.db

  • Your own image. Replace the core or classic folder next to your Dockerfile with the folder of the new archive, check the base image and the runtimes against the new version, and build the image again. See Installing using Docker (Core on Linux) and Installing using Docker (Classic on Windows).

After the upgrade, open the Licensing page of the admin portal. If it shows UNREGISTERED, register the server again as described in Licensing.

Upgrade to Version 5.0

  • .NET 10. DS Server 5.0 targets .NET 10 and no longer runs on the .NET 8 runtime of version 4.x. Install the ASP.NET Core Runtime 10.0, or the .NET 10 Hosting Bundle on Windows. Classic also needs the .NET Desktop Runtime 10.0, and it still needs the .NET Desktop Runtime 8.0 for its Document Editor worker process.
  • Base image. Build Linux images on mcr.microsoft.com/dotnet/aspnet:10.0 instead of 8.0.
  • Client packages. Update the NuGet and npm client packages to version 5.0.0. See Client-Side Libraries.
  • Plugins. Build plugins against the version 5.0 package TXTextControl.DocumentServices.Plugin.Abstractions; the sample plugin of Text Control targets .NET 10 with version 5.0.1 of the package. See Plugins.

Upgrade to Version 4.0

  • Two builds. Since 4.0, the archive has the folders core and classic instead of the files at its root. Replace a Windows installation of version 3.x with the classic folder, or move to the core folder on Linux or Windows. Scripts and Dockerfiles that extract the archive need the folder name in their paths.
  • Formats on Linux. The Core build on Linux reads and writes the document formats DOCX, HTML, PDF and XLSX only, and renders pages as SVG only. Check your documents before you move from Windows to Linux; Core and Classic lists the limits.
  • .NET 8. Version 4.x ran on .NET 8 instead of .NET 6.

Upgrade to Version 3.0

  • .NET 6. Version 3.0 moved from .NET Core 3.1 to .NET 6.
  • Hosting without IIS. IIS is no longer required: DS Server can run with dotnet, as a Windows service or in a container, and hostsettings.json sets its ports outside IIS.
  • Document Viewer code. In the ASP.NET Core package of the Document Viewer, SignatureSettings.SignatureBoxes and DocumentViewer.FrameBoxes changed their types, and loadDocument in JavaScript updates the viewer instead of initializing it again. Version 3.0 describes the changes.

Next Steps