Quick Start

Get PicPeak running in under five minutes with Docker, running the steps yourself.

Want a single command? Simple Install installs Docker, generates everything, and starts the stack for you.

Requirements: Docker v20.10+ and Docker Compose v2.0+. At least 2 CPU cores, 4 GB RAM (2 GB is workable only with UPLOAD_PROCESSOR_CONCURRENCY=1 — sharp/libvips decode peaks past 1.5 GB on heavy upload batches and OOM-kills the backend on smaller hosts, surfacing as 503s on thumbnails), 20 GB storage.

Clone the repository


git clone https://github.com/PicPeak/picpeak.git
cd picpeak

You don’t need to manage secrets: on first boot the stack generates JWT_SECRET, DB_PASSWORD, and REDIS_PASSWORD automatically. .env is optional and only holds overrides (domain, ports, SMTP). Copy the template if you want to set any:


cp .env.example .env   # optional

Any secret you do set in .env is used as-is. If you leave them unset, they’re generated once and persisted — never regenerated, so your database password can’t drift.

Create storage directories


mkdir -p events/active events/archived data logs backup storage

The backend container will chown these to its internal nodejs user on first boot — no PUID/PGID setup needed. If you’ve pinned user: in a compose override, see Permissions for the manual pre-chown step.

Start PicPeak

Production (recommended)


docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

Wait for all containers to report as healthy:


docker compose ps

Create your admin account

Open http://localhost:3000/admin. On a fresh install you’re taken to the /setup screen — paste the one-time setup token (from docker compose logs backend | grep -i "setup token" or data/SETUP_TOKEN) and set your email + password. See First Login for details.

The frontend (port 3000) serves the UI and proxies API requests to the backend (port 3001). You don’t need to access port 3001 directly.

Putting PicPeak on the internet? Any public server is probed by automated scanners within minutes. Before you share your first gallery link, read Bots and Scanners: a four-point checklist that takes ten minutes, plus an optional free shield in front of PicPeak. Installs that are only reachable inside your own network can skip it.

Next: First Login — create your admin account with the one-time setup token.