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.

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