System requirements
What a server needs to run ITSM Engine, by the number of agents working at the same time. The figures come from the load test, which measures the desk under a simulated working day.
Software
| Component | Requirement |
|---|---|
| Operating system | Linux with a recent kernel. Any distribution that runs Docker Engine is fine. |
| Container runtime | Docker Engine 25 or later with Docker Compose 2.24 or later, for the recommended setup. Tested with Docker 29 and Compose 5. Podman, or a platform that builds from a Dockerfile, works for other ways to run it. |
| Database | PostgreSQL 17. Included in the compose setup; a managed PostgreSQL 17 service works too. |
| File storage | S3-compatible object storage. Included in the compose setup (MinIO); any S3-compatible service works. |
| An SMTP server or a Resend account, for sending. Receiving replies by email needs one of the inbound routes. | |
| Network | A domain with an A/AAAA record pointing to the server, and ports 80 and 443 open for HTTPS and certificate renewal. |
| Browsers | A current version of a mainstream browser, for agents and requesters. The automated end-to-end tests run in Chromium. |
Hardware
[!IMPORTANT] Size the server by agents online: people signed in and working at the same time, not the number of agent accounts. A desk with 3,000 agents across three shifts may have 1,000 online at once.
For the Standard setup, with the application, PostgreSQL, storage and Caddy on one server:
| Agents online | CPU | Memory | Disk |
|---|---|---|---|
| Up to 100 | 2 vCPU | 2 GB | 20 GB |
| Up to 500 | 2 vCPU | 4 GB | 40 GB |
| Up to 1,000 | 4 vCPU | 4 GB | 60 GB |
| Up to 2,000 | 4 vCPU | 8 GB | 100 GB |
| Up to 3,000 | 4 vCPU | 8 GB | 100 GB |
| More than 3,000 | Scale |
These sizes leave about half the capacity free at the top of each range, for peaks, backups and growth.
Building the image on the server needs about 2 GB of memory on its own; on a 2 GB server, build elsewhere or add swap.
Measured use
Measured at the top of each range (load test):
| Agents online | Application | PostgreSQL | Caddy | Response time, 95% of requests |
|---|---|---|---|---|
| idle | 0.31 GB, 0.03 cores | 0.18 GB, 0.06 cores | 0.03 GB | |
| 500 | 0.43 GB, 0.2 cores | 0.26 GB, 0.2 cores | 0.17 GB | 34 ms |
| 1,000 | 0.49 GB, 0.3 cores | 0.26 GB, 0.4 cores | 0.30 GB | 34 ms |
| 2,000 | 0.89 GB, 0.4 cores | 0.26 GB, 0.6 cores | 0.53 GB | 61 ms |
| 3,000 | 1.04 GB, 0.6 cores | 0.27 GB, 0.9 cores | 0.79 GB | 124 ms |
- Caddy's memory grows with the open live-update connections, one per agent's browser tab.
- The storage service (MinIO) used about 0.08 GB throughout.
Disk
Plan disk from the size of your data, not the number of agents:
| Part | Space |
|---|---|
| Database | About 0.7 GB for 200,000 cases with 1,000,000 messages, contacts and accounts, indexes included. Grow it in proportion to the number of messages you keep. Housekeeping removes old data on the schedule you set. |
| Files | Attachments, logos and exports, at their own size, in the storage bucket. |
| Backups | Each backup is a compressed database dump plus a copy of the files. Keep room for as many as you retain, or send them to other storage (backups). |
| Images and logs | About 5 GB for Docker images, build cache and container logs. |
[!TIP] Use SSD storage for PostgreSQL.
PostgreSQL settings
The bundled PostgreSQL uses its defaults, which suit a small desk. From about 500 agents online:
| Setting | Advice |
|---|---|
shared_buffers | About 25% of the server's memory. Ideally the whole database fits in memory. |
max_connections | The default of 100 is enough for Standard. The application keeps up to DATABASE_POOL_SIZE connections (20 by default) and its job queue up to 10 more. |
| Separate server | A managed PostgreSQL 17 service, or PostgreSQL on its own server, takes database load off the application server. Point DATABASE_URL at it (configuration). |
Beyond one server
On Standard, the first limit is the application process: one Node.js process handles requests on one CPU core. In the load test it used 0.6 of a core at 3,000 agents online, so it has room left, but less than the server as a whole.
[!NOTE] Adding CPU cores to the server doesn't move this limit; more application servers do.
That is what Scale is for, and two application servers carried the same 3,000 agents at under half a core each.