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
| Item | Minimum |
|---|---|
| Server | Windows Server or Linux, 2 CPU, 4 GB RAM, 20 GB disk (about 10–50 users) |
| Software | Node.js 24 LTS or newer |
| Network | A name such as kpi.yourcompany.com, an HTTPS certificate, and a reverse proxy (IIS, Nginx, a cloud load balancer) |
| Storage | The 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 -- admin@yourcompany.com "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)
| Variable | Default | Meaning |
|---|---|---|
PORT | 3000 | Port on 127.0.0.1 |
DATA_DIR | data/db | Database folder |
BACKUP_DIR | data/backups | Backup folder |
BACKUP_KEEP | 14 | Backups kept |
BACKUP_EVERY_HOURS | 24 | Hours between automatic backups |
COOKIE_SECURE | – | Set to true behind HTTPS (required in production) |
4. Run it as a service
- Linux (systemd): a service that runs
npm startin the application folder, restarts on failure, with the variables above. - Windows: a service wrapper (for example NSSM) running
npm.cmd startin the application folder.
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
- Automatic: one at start and every 24 hours in
BACKUP_DIR(filescsworkhub-YYYYMMDD-HHMMSS.tar.gz). - Now:
npm run backup(with the service stopped). - Restore: stop the service,
npm run restore -- data/backups/<file>, start it again. The current database is moved aside, never deleted. - Copy
BACKUP_DIRto another place every day (another server or cloud storage).
7. Updating to a new version
- Make a backup. 2. Stop the service. 3. Replace the application files (keep
data/). 4.npm ciandnpm test. - 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
| Message | What 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 |