System Requirements
Minimum requirements
- CPU: 2 CPU cores, 64-bit ARM or x86-64 with at least the x86-64-v2 instruction set. See CPU compatibility, especially on a virtual machine
- RAM: 4 GB minimum for a normal photo-upload workload — sharp/libvips decodes the full uncompressed frame before resize, and the default two worker loops at sharp-concurrency 2 can push peak RSS past 1.5 GB on a batch of 20-MP+ photos. On a 2 GB VPS that’s enough to OOM-kill the backend mid-batch (surfaces as 503s on thumbnails — see Low-memory hosts for the recipe to run on 2 GB).
- Storage: 20 GB minimum (plus photo storage needs)
- OS: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
- Node.js: v22.12.0 or higher, for native installs and builds from source (the Docker images bring their own Node.js 22). The installer installs Node.js 22 on a native install
- Database: SQLite (included) or PostgreSQL 12+
CPU compatibility
PicPeak processes images with Sharp . On x86-64 Linux, Sharp’s prebuilt binaries need the x86-64-v2 instruction set (SSE4.2, POPCNT and others). This applies to the Docker images, the all-in-one image and native installs alike. 64-bit ARM hosts are not affected.
Almost every physical x86-64 CPU sold since about 2010 has these instructions. The usual cause of trouble is a virtual machine whose virtual CPU hides them, even though the physical CPU has them.
The server starts normally, so the problem only shows on the first image upload. Every image is then refused with an error containing:
Could not load the "sharp" module
Unsupported CPU: Prebuilt binaries for Linux x64 require v2 microarchitectureOlder versions report this as Invalid image file. The photo is fine: there is no need to investigate it, or your volumes, permissions, firewall or reverse proxy. Current versions name the CPU in the error and log IMAGE PROCESSING IS UNAVAILABLE at startup.
Check a host
Run this on the machine or VM that runs PicPeak, not on the hypervisor:
for f in cx16 lahf_lm popcnt pni ssse3 sse4_1 sse4_2; do grep -qw "$f" /proc/cpuinfo || echo "missing: $f"; doneNo output means the CPU exposes everything x86-64-v2 needs.
Proxmox VE
New VMs created in the web interface default to x86-64-v2-AES, which works. VMs set to kvm64, which is also the default for VMs created without the web interface, or qemu64 do not.
- Shut the VM down. A reboot from inside the guest does not apply the change.
- Open the VM, then Hardware → Processors → Edit.
- Set Type to
x86-64-v2-AES, orx86-64-v2if the host CPU has no AES support. - Start the VM.
host works too and passes through every feature of the physical CPU, but it can break live migration between nodes with different CPUs. On a cluster, choose the newest CPU type that every node supports.
Other hypervisors have an equivalent setting: pick a CPU model at Nehalem level or newer, or host passthrough.
Docker requirements (recommended)
- Docker: v20.10.0+
- Docker Compose: v2.0.0+
Low-memory hosts
Running on 2 GB RAM (e.g. an entry-level VPS) is workable but requires tuning the upload-processor concurrency down. The backend auto-detects total RAM at startup via os.totalmem() — on a host that reports < 3 GB, it defaults UPLOAD_PROCESSOR_CONCURRENCY to 1 instead of 2 and logs a one-shot warning. You can pin the value explicitly in .env:
# Single worker loop — slower batch processing, lower peak RSS
UPLOAD_PROCESSOR_CONCURRENCY=1The trade-off is throughput: a single worker processes one photo at a time, so a 100-photo batch takes ~2× as long but won’t OOM.
Health-check note: if the backend dies under memory pressure, the gallery serves 503 Service Unavailable on thumbnails until Docker’s restart: unless-stopped brings the container back. Persistent 503s during/after an upload batch on a low-memory host are almost always this.
Video support requirements
When enabling video uploads, consider these additional resources:
| Resource | Recommendation | Notes |
|---|---|---|
| RAM | 4 GB+ recommended | FFmpeg processing requires more memory |
| Storage | Plan for 10–100× more | Videos are significantly larger than images |
| CPU | Additional cores help | Video thumbnail extraction is CPU-intensive |
| Bandwidth | Higher throughput | Video streaming requires more bandwidth |
Technical notes:
- FFmpeg is bundled via npm (
@ffmpeg-installer/ffmpeg) — no system installation required. - Maximum upload size: 10 GB per video file.
- Chunked upload support for files > 100 MB (resumable uploads).
- Supported formats: MP4, WebM, MOV, AVI.
- Video thumbnails are automatically generated from the first few seconds.
For Nginx / reverse proxy: if using Nginx, increase the client max body size:
client_max_body_size 10G;
proxy_read_timeout 3600;
proxy_send_timeout 3600;See Reverse Proxy for the full proxy configuration.