Installing on Linux (systemd and nginx)

Installing on Linux (systemd and nginx)

On this page

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.

nginx ends TLS and forwards to the application on localhost:5000, which runs as a systemd service.

1. Runtime#

bash
# 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.0

On 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#

bash
# copy the release (publish) folder to /opt/worksmarthub, then:
sudo useradd --system --shell /sbin/nologin worksmarthub
sudo chown -R worksmarthub:worksmarthub /opt/worksmarthub

The 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:

ini
[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.target
bash
sudo systemctl daemon-reload
sudo systemctl enable --now worksmarthub-app
journalctl -t WorkSmartHub -f

WorkingDirectory 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#

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#

  1. Install a newer .NET runtime first if the release needs it.
  2. Back up, then sudo systemctl stop worksmarthub-app.
  3. Keep appsettings.json, copy the new files, put it back, and chown -R worksmarthub:worksmarthub /opt/worksmarthub.
  4. 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.

Did not find what you need?

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

Contact us