Knowledge Base › Troubleshooting › Upgrading OneSigner Safely on a Production Signing Host

Upgrading OneSigner Safely on a Production Signing Host

Nov 2, 2026 · 3 views

This guide provides a methodical procedure to update OneSigner on a live Windows machine without disrupting active automated signing workflows, watched folders, or REST API clients.

Prerequisites and Impact Analysis

Before initiating an update, verify your current license status and ensure you have administrative access to the Windows host. Note that OneSigner requires one Windows machine that stays on with the hardware token plugged in. Upgrading stops and restarts the OneSigner Windows service and closes the configuration and tray app, so REST API requests fail and watched folders are not processed while the installer runs. Use Check for Updates in the OneSigner configuration tool to see whether a newer build is available to your license: a perpetual license keeps working with all features after its update coverage ends, but newer builds are only offered while that coverage is current. For license questions, see License Activation. Plan your maintenance window during off-peak hours when automated PDF and code-signing volume is lowest.

Step-by-Step Upgrade Procedure

Execute the following numbered sequence on your production Windows host to replace the application binaries cleanly while preserving your configuration files, cryptographic profiles, and database states.

  1. Log in to the Windows machine hosting OneSigner using an account with local administrator privileges. Ensure the physical hardware token (such as a YubiKey, SafeNet, or ePass2003 device) remains securely plugged into the USB port during the entire procedure.
  2. Open the Windows Services manager (services.msc), locate the OneSigner service, right-click it, and select Stop. Alternatively, open an elevated PowerShell terminal and execute the stop command:
Stop-Service -Name "OneSignerService"
  1. Close any active instances of the OneSigner GUI application from the Windows system tray or task manager to release file locks on the installation directory.
  2. Back up C:\OneSigner\app\appsettings.json (your whole configuration), portal.db and the portal-docs folder in the same directory (portal users and documents), or the same files under your custom installation path, to a secure location outside the application folder. Treat the copy of appsettings.json as sensitive: it carries the settings the service needs to sign unattended.
  3. Run the new OneSigner installer and keep the same destination folder. The installer stops the service itself, leaves your existing appsettings.json in place, and re-registers and starts the service when it finishes.
  4. If the service is not running after the installer finishes, start it through services.msc or from your elevated PowerShell terminal:
Start-Service -Name "OneSignerService"

Verification and Post-Upgrade Checks

Once the service restarts, you must verify that the environment is fully operational before releasing the host back to production traffic. Open the OneSigner configuration tool, confirm the service reports Running and the License tab shows a valid license, and check that your token certificates still appear in your signing profiles. Then check Windows Event Viewer (Windows Logs > Application) for errors from the OneSigner service since the restart. Send a test PDF file to one of your configured watched folders or execute a dry-run test against your REST API endpoint using a tool like curl to verify that signing operations complete successfully. If you encounter unexpected behavior or missing configuration parameters, consult the troubleshooting steps outlined in Common Errors & Solutions to resolve common path or permission conflicts.

Handling Hardware Tokens and Driver Dependencies

Major updates occasionally require updated cryptographic middleware for your USB hardware tokens. If your signing operations fail immediately after an upgrade with cryptographic provider errors, verify that your SafeNet Client, YubiKey Smart Card Minidriver, or ePass middleware is up to date and responding correctly to Windows CryptoAPI calls. Ensure that Windows power management settings on the host machine are configured to disable USB selective suspend, preventing the operating system from putting your hardware token into a low-power sleep state during idle periods. If build servers elsewhere need to sign while the token stays on this host, see Azure Key Vault Proxy (Remote Signing). It still signs with the local token, so the host must stay online with the token plugged in.