Deployment

IAM Role Configuration

To facilitate the server's access to Google Cloud Storage data, it is essential to assign appropriate IAM roles. The instance should be configured with a service account that has the storage.objectViewer role for the required GCS buckets. This ensures the necessary permissions for data retrieval.

Enhancing Security

For enhanced security, it is strongly advised to disable the public IP address associated with the instance or use a firewall rule to restrict access to the API Server. This precautionary measure limits access to the API Server, thereby reducing potential security risks.

Optimizing Network Deployment

To minimize data transfer costs, it is recommended to deploy the server within the same region as your existing infrastructure. By colocating the virus scan server and your other resources in the same region, you can take advantage of the free data transfer within the same region. This setup also ensures that the virus scan API server operates within the same network environment as your infrastructure, enabling faster and more efficient communication while minimizing data transfer costs.

VM size

The server requires a minimum of 3GB of memory to function properly, as it needs to load the virus database into memory for fast scanning. Using instances with less than 3GB of memory could cause ClamAV to fail during virus definition updates and scanning operations. The recommended VM size is 2 CPU cores and 4GB of memory.

Server Configuration

The API server reads its configuration from environment variables. The defaults are suitable for most deployments.

Variable	Default	Description
`CLOUD_PROVIDER`	`gcp`	Cloud storage provider to mount. Only one provider is active per process.
`MAX_SCAN_SIZE_MB`	`500`	API request limit: maximum file size accepted before scanning. Larger files are rejected with HTTP `413`. This is separate from ClamAV's own engine limits — see Scan Size Limits.
`REQUEST_TIMEOUT_SECS`	`300`	Per-request timeout so a slow download or stuck scan cannot hold a slot indefinitely.
`MAX_CONCURRENT_SCANS`	`10`	Maximum number of scans running concurrently.
`LOCAL_SCAN_DIR`	(unset)	When set to a directory, enables the `POST /api/v1/scan` local-path route, restricted to files under that directory. When unset, the route is not mounted.

Scan Size Limits

There are two independent size limits, enforced at different stages. They are not the same, and the smaller one effectively wins.

1. API request limit (MAX_SCAN_SIZE_MB, 500MB by default). This is a gate applied by the API server before a file is scanned — on the uploaded body, the local file's size, or the GCS object's size. A file exceeding this limit is rejected with HTTP 413 and code: 99, and is never passed to ClamAV.

2. ClamAV engine limits (MaxFileSize, MaxScanSize, MaxRecursion). These are enforced by the ClamAV scan engine during the scan. The image ships with AlertExceedsMax enabled, so a file that passes the API gate but exceeds an engine limit is flagged with a virus name starting Heuristics.Limits.Exceeded. This is reported like an infected result: HTTP 200 with code: 1 — not a 413.

Because ClamAV's engine limits are smaller than the 500MB API gate, a mid-sized file can pass the API check yet still be flagged with Heuristics.Limits.Exceeded by the engine. If a scan is expected to trigger this alert, please contact us at support@elmcomputing.io.

Health Checks

The server exposes two probes under /api/v1 for use with load balancers and managed instance groups:

Readiness — GET /api/v1/health returns 200 only when ClamAV is working and reports a probe file clean; otherwise 503. Route traffic on success.
Liveness — GET /api/v1/livez returns 200 immediately without invoking ClamAV. Use this for restart-on-failure checks so a transient ClamAV issue drains traffic without restarting the process.