Installing on Windows (IIS)

Installing on Windows (IIS)

On this page

IIS hosts WorkSmartHub in-process: it manages the process and acts as the reverse proxy, so no separate Windows service is needed. Because the background jobs run inside the web process, IIS must keep that process running even when nobody uses the site.

IIS hosts the application in-process in an always-running application pool; the data stays in the site folder or in an external database.

1. Prerequisites#

  1. Install the Web Server (IIS) role with Application Development → Application Initialization. Add Security → Windows Authentication only for Active Directory sign-in.
  2. Install the ASP.NET Core 10.0 Hosting Bundle (from the official .NET download site, .NET 10.0, ASP.NET Core Runtime), then run iisreset.
  3. Install the Microsoft Visual C++ Redistributable (x64). The licence handling depends on it; without it the application reports a libsodium error at start.
  4. Check the runtime with dotnet --info.

2. Copy the files#

Copy the contents of the release (publish) folder into the site folder, for example C:\inetpub\wwwroot\WorkSmartHub. The folder must directly contain WorkSmartHub.dll, web.config, appsettings.json and wwwroot.

3. Application pool#

Create a pool with .NET CLR version: No Managed Code and the Integrated pipeline. In Advanced Settings:

Setting Value Why
Start Mode AlwaysRunning Starts with IIS, not with the first request
Idle Time-out (minutes) 0 IIS never stops the process for being idle
Identity A dedicated service account
Load User Profile True Needed by some authentication setups
Regular Time Interval (minutes) 0, or a specific time outside working hours and job times A recycle interrupts running work

Give the pool identity Modify permission on the site folder. The application writes there: Logs\, the SQLite database (database.db with -wal and -shm), FileStorage\, the live templates, and appsettings.json itself (at start it adds settings that a new release introduced, after saving a backup copy).

4. Site#

  1. Add Website: choose the pool, the site folder and the binding.
  2. Site Advanced Settings → Preload Enabled: True.
  3. Serve the site over HTTPS (at the binding or at a load balancer). A proxy in front must set X-Forwarded-Proto and X-Forwarded-Host itself.
  4. Active Directory sign-in (Windows only): the server must be domain-joined; enable both Anonymous Authentication and Windows Authentication on the site. For users in many groups, raise the HTTP.sys header limits (MaxFieldLength 65534, MaxRequestBytes 16777216 under HKLM\System\CurrentControlSet\Services\HTTP\Parameters) and restart.
  5. In web.config, add shutdownTimeLimit="60" to the aspNetCore element, so a recycle gives the application time to finish its work (it needs up to 45 seconds).
  6. Start the pool and browse the site. GET /health answers 200 when the application is up.

5. Configure#

Edit appsettings.json in the site folder: database, cache, user store and login, signing keys, PublicBaseUrl, e-mail, logging (Configuration). Under IIS HttpSettings.Urls is not used; leave the default. Recycle the pool after changes.

Background jobs run at the configured times in the server's local time; keep pool recycles away from them.

Updating#

  1. If the new release needs a newer .NET version, install its Hosting Bundle and run iisreset.
  2. Back up the database and the site folder, then stop the pool.
  3. Keep a copy of appsettings.json.
  4. Copy the new files over the site folder, then put your appsettings.json back. Edited templates are kept.
  5. Start the pool. The database is migrated at start.

Without IIS#

Any Windows service wrapper that runs dotnet WorkSmartHub.dll in the application folder works, with a reverse proxy to localhost:5000. Give the wrapper a stop timeout of at least 60 seconds and start it automatically. For Active Directory, IIS is recommended.

The full step-by-step text is in the backend README of the release.

Did not find what you need?

Write to us or book a call. We answer questions about features, installation and licensing.

Contact us