Skip to Content
DeploymentSystem Requirements

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 microarchitecture

Older 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"; done

No 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.

  1. Shut the VM down. A reboot from inside the guest does not apply the change.
  2. Open the VM, then Hardware → Processors → Edit.
  3. Set Type to x86-64-v2-AES, or x86-64-v2 if the host CPU has no AES support.
  4. 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: 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=1

The 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:

ResourceRecommendationNotes
RAM4 GB+ recommendedFFmpeg processing requires more memory
StoragePlan for 10–100× moreVideos are significantly larger than images
CPUAdditional cores helpVideo thumbnail extraction is CPU-intensive
BandwidthHigher throughputVideo 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.

Last updated on