﻿# 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,…

Source: https://workwise-solutions.net/docs/installation/linux/ · Language: en · Hungarian version: https://workwise-solutions.net/hu/docs/installation/linux/

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.

![WorkSmartHub on Linux with systemd and nginx](https://workwise-solutions.net/docs/images/diagram-install-linux-en.png)
*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](https://workwise-solutions.net/docs/installation/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](https://workwise-solutions.net/docs/installation/docker/).
