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.
1. Prerequisites#
- Install the Web Server (IIS) role with Application Development → Application Initialization. Add Security → Windows Authentication only for Active Directory sign-in.
- 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. - Install the Microsoft Visual C++ Redistributable (x64). The licence handling depends on it; without it the application reports a
libsodiumerror at start. - 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#
- Add Website: choose the pool, the site folder and the binding.
- Site Advanced Settings → Preload Enabled: True.
- Serve the site over HTTPS (at the binding or at a load balancer). A proxy in front must set
X-Forwarded-ProtoandX-Forwarded-Hostitself. - 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 (
MaxFieldLength65534,MaxRequestBytes16777216 underHKLM\System\CurrentControlSet\Services\HTTP\Parameters) and restart. - In
web.config, addshutdownTimeLimit="60"to theaspNetCoreelement, so a recycle gives the application time to finish its work (it needs up to 45 seconds). - Start the pool and browse the site.
GET /healthanswers200when 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#
- If the new release needs a newer .NET version, install its Hosting Bundle and run
iisreset. - Back up the database and the site folder, then stop the pool.
- Keep a copy of
appsettings.json. - Copy the new files over the site folder, then put your
appsettings.jsonback. Edited templates are kept. - 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.