CS WorkHub ← Back to the site

CS WorkHub – Installation guide (for the customer's IT team)

This guide installs CS WorkHub on one server of the customer (self-hosted license). It takes about one hour.

1. Requirements

ItemMinimum
ServerWindows Server or Linux, 2 CPU, 4 GB RAM, 20 GB disk (about 10–50 users)
SoftwareNode.js 24 LTS or newer
NetworkA name such as kpi.yourcompany.com, an HTTPS certificate, and a reverse proxy (IIS, Nginx, a cloud load balancer)
StorageThe data/ folder must be on a disk that is kept across restarts and backed up
Email (optional)A mailbox for reminders (the email service is configured in a later version)

The application listens only on 127.0.0.1 (the same server). The reverse proxy receives the users over HTTPS and passes them on. Never open port 3000 to the network directly.

2. Install

npm ci                      # installs the exact library versions of package-lock.json
npm test                    # every test must pass
npm run setup-admin -- [email protected] "Admin Name"

setup-admin prints a one-time activation link (valid 72 hours). The administrator opens it once the site is reachable and chooses a password (at least 10 characters).

3. Settings (environment variables)

VariableDefaultMeaning
PORT3000Port on 127.0.0.1
DATA_DIRdata/dbDatabase folder
BACKUP_DIRdata/backupsBackup folder
BACKUP_KEEP14Backups kept
BACKUP_EVERY_HOURS24Hours between automatic backups
COOKIE_SECURE–Set to true behind HTTPS (required in production)

4. Run it as a service

Stop it with the service manager (it closes the database cleanly), never by killing the process.

5. Reverse proxy

Forward https://kpi.yourcompany.com/ to http://127.0.0.1:3000/, keep the Host header and the cookies, and redirect HTTP to HTTPS.

6. Backups and restore

7. Updating to a new version

  1. Make a backup. 2. Stop the service. 3. Replace the application files (keep data/). 4. npm ci and npm test.
  2. Start the service. Database changes ("migrations") are applied by themselves at start.

8. Loading the KPIs

In Administration: create the plan, add the team in the X-Matrix (Associate → Team member), then load the KPIs with the templates, saved as Excel (.xlsx) or CSV (Administration → Load KPIs; templates in templates/ or in My Tracker → My Templates).

9. Messages you may see

MessageWhat to do
"The server is running (process N)"A command needs the service stopped. Stop it and run the command again
"The server could not start… port 3000"Another program uses the port. Change PORT
"The database is newer than this program"An older version was installed over a newer database. Install the newer version