Self-hosted installation with Docker
From an empty Linux VM to a working portal. Roughly an hour, most of which is DNS and TLS rather than the application.
System requirements
| Employees | vCPU | RAM | Disk (no screenshots) | Disk (screenshots, 30-day retention) |
|---|---|---|---|---|
| Up to 25 | 2 | 4 GB | 40 GB | ~100 GB |
| Up to 100 | 4 | 8 GB | 80 GB | ~280 GB |
| Up to 250 | 8 | 16 GB | 160 GB | ~660 GB |
- Any Linux distribution with Docker Engine 24+ and the compose plugin.
- A DNS record pointing at the host, for example
hr.yourcompany.com. - A TLS certificate, or ports 80 and 443 open so the bundled proxy can obtain one.
- An SMTP relay for notification email.
Install
# 1. unpack the stack supplied with your licence
tar xzf employeedesk-selfhosted.tar.gz
cd employeedesk
# 2. configure
nano .env
# 3. start
docker compose up -d
# 4. watch it come up
docker compose logs -f app
# 5. confirm
curl -fsS https://hr.yourcompany.com/api/healthEnvironment variables
| Variable | Purpose | Example |
|---|---|---|
| MONGO_URI | MongoDB connection string. The one variable you must get right. | mongodb://db:27017/employeedesk |
| CLIENT_URL | Public URL of the portal. The desktop tracker is configured with this. | https://hr.yourcompany.com |
| JWT_SECRET | Signs session tokens. Generate a long random value per installation. | (64 random characters) |
| PORT | Port the application listens on behind your reverse proxy | 4002 |
| SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS / SMTP_FROM | Notification and invitation email | smtp.yourcompany.com |
| TRACKER_RETENTION_DAYS | Days before screenshots are deleted | 30 |
| TRACKER_SCREENSHOT_MIN_MIN / _MAX_MIN | Randomised capture interval, in minutes | 2 / 10 |
| TRACKER_SHOW_SHOTS_TO_EMPLOYEE | Employees see their own captures. Leave this on. | true |
| WORK_START_HOUR / WORK_START_MINUTE / LATE_GRACE_MINUTES | Default shift and grace window | 9 / 30 / 30 |
| TZ | Server timezone, which attendance calculations use | Asia/Kolkata |
Set TZ before anyone marks attendance. Changing the server timezone after a month of records has been written means the shift comparisons for those records were made against a different reference. It is a fixable mess, but only if you notice.
TLS
The bundled reverse proxy will obtain and renew a certificate automatically if ports 80 and 443 reach the host. If you terminate TLS at an existing load balancer or corporate proxy instead, disable the bundled proxy and forward to the application container on its internal port, passing the usual forwarded headers.
First-run checklist
- Create the administrator accountThe first sign-up on a fresh installation becomes the administrator. Do this immediately after the stack is up.
- Set the company profile and timezoneCompany name, working days, and confirm the timezone matches the TZ variable.
- Configure shifts and leave typesBefore importing employees, so imported people land on the right policy.
- Import employeesCSV import from the admin area. Invitations go out over your configured SMTP relay, so test mail first.
- Set screenshot retentionEven if screenshots are off. Setting it now avoids the conversation happening after captures exist.
- Configure and test a backupFollow the backup guide and restore once into a scratch database. An untested backup is not a backup.
Health check
GET /api/health returns HTTP 200 with the application version, database connectivity and queue status. Point your monitoring at it.
Related
Frequently asked
Can we use an external MongoDB instance?
Yes. Point MONGO_URI at your existing MongoDB server or a managed instance such as Atlas, and remove the bundled db service from the stack. Nothing else changes.
Can we put screenshots in S3?
Yes. Set the storage driver to S3 and supply a bucket and credentials. This is the usual choice when disk growth on the application host is a concern.
Does it need to reach the internet?
Only for a licence check, or nothing at all with an offline licence file. Air-gapped installations use an offline licence file and images loaded from a tarball, and then make no outbound connection at all.
Something missing from the docs?
Tell us what you were looking for at support@employeedeskcrm.com and we will add it here.
- 7-day trial
- No credit card
- Cancel anytime