Installing on Linux (systemd and nginx)
The application runs as a systemd service under a dedicated user, with nginx as the reverse proxy. The commands are for Ubuntu and Debian; the Red Hat family (RHEL, CentOS Stream, Rocky, Alma, Oracle Linux) differences are noted. Active Directory sign-in is not available on Linux; use Local, LDAP, Entra ID or OAuth.
1. Runtime#
# Ubuntu 24.04 and newer
sudo apt-get update && sudo apt-get install -y aspnetcore-runtime-10.0
# Ubuntu 22.04: Canonical's backports PPA
sudo add-apt-repository -y ppa:dotnet/backports
sudo apt-get update && sudo apt-get install -y aspnetcore-runtime-10.0
# Red Hat family
sudo dnf install -y aspnetcore-runtime-10.0On Debian, register the Microsoft package repository first. Use one package source only, and check with dotnet --list-runtimes (Microsoft.AspNetCore.App 10.0.x). If your database, SMTP server, Vault or identity provider uses an internal CA, add the CA to the system trust store.
2. Application files and user#
# copy the release (publish) folder to /opt/worksmarthub, then:
sudo useradd --system --shell /sbin/nologin worksmarthub
sudo chown -R worksmarthub:worksmarthub /opt/worksmarthubThe application writes below this folder: Logs/, the SQLite database, FileStorage/, the live templates, and appsettings.json.
3. systemd service#
/etc/systemd/system/worksmarthub-app.service:
[Unit]
Description=WorkSmartHub
After=network.target
[Service]
Type=simple
Restart=always
RestartSec=3
User=worksmarthub
WorkingDirectory=/opt/worksmarthub
ExecStart=/usr/bin/dotnet /opt/worksmarthub/WorkSmartHub.dll
TimeoutStopSec=75
SyslogIdentifier=WorkSmartHub
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now worksmarthub-app
journalctl -t WorkSmartHub -fWorkingDirectory matters, because relative paths resolve against it. TimeoutStopSec=75 gives the application time to stop cleanly.
4. Configure#
Edit /opt/worksmarthub/appsettings.json (Configuration) and restart the service. Keep HttpSettings.Urls at http://localhost:5000 behind nginx; change it to http://+:5000 only when exposing the application directly. Use one entry per port.
5. nginx#
server {
listen 443 ssl http2;
server_name wsh.example.com;
ssl_certificate /opt/ssl/certificate.crt;
ssl_certificate_key /opt/ssl/certificate.key;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}In the http block set client_max_body_size 50m; (uploads are sent in 25 MB chunks; the nginx default of 1 MB refuses them) and timeouts of 600 seconds. nginx must overwrite the forwarded headers, never pass client values through. On the Red Hat family with SELinux, run sudo setsebool -P httpd_can_network_connect 1; with firewalld, open http and https.
Set PublicBaseUrl to the public address.
Updating#
- Install a newer .NET runtime first if the release needs it.
- Back up, then
sudo systemctl stop worksmarthub-app. - Keep
appsettings.json, copy the new files, put it back, andchown -R worksmarthub:worksmarthub /opt/worksmarthub. - Start the service; the database is migrated at start.
Alternatives: the same unit can run as a systemd user service (enable lingering with loginctl enable-linger), or run the application in Docker.