Paul NothaftandPaul Nothaft
37a15e3d49
* fix(faces): restore the :beta image tag and surface sidecar health
Both halves of what a user hit on discussions/1069: the People card sat
at "Scanning… 0 of 227" for 30 minutes with no explanation, because the
sidecar container could never have started.
docker-build.yml — republish `:beta`. It used to come for free via
`type=ref,event=branch` when the active development branch was literally
named `beta`; the rename to `main` silently retired it. backend:beta has
been frozen at 2026-06-29 (448da950) ever since while :main moved on, so
PICPEAK_CHANNEL=beta has been serving a seven-week-old build across every
image. The ml sidecar was added after the rename and so never had a
`:beta` at all, which left docker-compose.production.yml:158 unable to
resolve ghcr.io/picpeak/picpeak/ml for any documented channel — the
image simply does not exist as :beta or :stable, only as :main and
pinned versions. Tag added to all four merge jobs, gated on main.
`:stable` stays absent for ml on purpose: it is gated on refs/heads/stable
and the sidecar does not exist there. stable's docker-compose.production.yml
carries no picpeak-ml service, so nothing can reference the missing tag.
FaceRecognitionCard — show when the sidecar is unreachable. An
unreachable sidecar is not an error by design: faceQueue.js:132-136
releases the photo back to `pending` and retries forever so a restart
does not burn the queue. The cost was that a stopped container looked
exactly like a slow scan, indefinitely, and the only signal was a
backend log line rate-limited to once per five minutes.
/admin/events/faces/health already existed and nothing in the frontend
called it. It is now polled while a scan is in progress, and a failing
check replaces the spinner with the sidecar URL, the underlying error
(which distinguishes a stopped container from a token mismatch) and the
command to start it.
Health is only polled while a scan is running — an idle card has no
reason to care whether the sidecar is up.
* fix(faces): tell the three sidecar failure modes apart
Follow-up to the health surface in this branch, from an external review
pass. The original warning was right about "the sidecar is not working"
and wrong about almost everything after that.
faceClient.checkHealth now returns a `reason` rather than only a message,
because the caller has to know whether photos survive:
- 'unauthorized' (401) and 'rejected' (any other 4xx) both become
SidecarRejectedError in classify(), which workerLoop does NOT retry —
every claimed photo is marked 'failed'. Telling the admin the scan
resumes on its own was simply untrue there; both now say to fix the
cause and Re-scan.
- 'unreachable' (refused/DNS/timeout/5xx) is the retryable one.
The card also no longer cries wolf. /faces runs inference synchronously
inside an `async def`, so one slow photo blocks the event loop and stalls
/info past its 5s timeout — a healthy sidecar can fail a probe. Verified
with an isolated uvicorn repro: a blocking call in an async handler
stalled the sync /info endpoint to 5.01s. The warning now needs three
consecutive failures AND no drop in `pending`. Three because a single
/faces call may legitimately run to FACE_ML_TIMEOUT_MS (30s) and two
probes 15s apart both fit inside that window; `pending` rather than
`scanned` because scanned counts only 'done', so a run producing
skipped/failed photos is progress that counter misses.
A 4xx burns the queue with no backoff, so it can empty before anyone
opens the card — in_progress goes false and only "227 failed" is left.
The probe therefore also runs when a finished scan has failures, and the
notice renders under the counts instead of replacing them. It is worded
as present-tense service state, not as a claim about those specific
failures: a live probe cannot know whether they came from this
misconfiguration or from corrupt images earlier. Attributing them exactly
needs stored face_error rows, which is a bigger change than this.
Also adds the missing-token case to the unreachable text: FACE_ML_TOKEN
has no default and the container refuses to start without it, so the most
likely first run fails as a plain connection refusal that "just start it"
does not fix.
---------
Co-authored-by: Paul Nothaft <[email protected]>
📸 PicPeak
Open-source, self-hosted photo sharing for events.
PicPeak is a powerful, self-hosted open-source alternative to commercial photo-sharing platforms like PicDrop.com and Scrapbook.de. Built for photographers and event organizers, it makes it simple to share beautiful, time-limited photo galleries with clients while keeping full control over your data and branding.
Important
PicPeak has moved to its own GitHub organization. Docker images are now at
ghcr.io/picpeak/picpeak/{backend,frontend}and active development is onmain. The oldghcr.io/the-luap/...path still responds but its tags are frozen at 2026-05-27 — if updates never arrive, check your image path first. Seedocs/migration-to-org.mdfor the one-linedocker-compose.ymledit.
Contents
- Live Demo
- Quick Start
- Why PicPeak?
- Features
- Documentation
- Comparison
- Tech Stack
- Contributing & Support
- License
🎮 Live Demo
Try PicPeak without installing anything — demo.picpeak.app · admin panel
| Password | |
|---|---|
[email protected] |
Demo2026! |
The demo resets periodically. Uploaded content may be removed without notice.
🚀 Quick Start
Get PicPeak running in under 5 minutes:
# Clone the repository
git clone https://github.com/PicPeak/picpeak.git
cd picpeak
# Copy the environment template — the defaults work out of the box.
# Machine secrets (JWT, DB, Redis) are auto-generated on first run, and the
# admin account is created in the browser. Edit .env only to customise
# (domain, SMTP, storage paths, …) — nothing is required.
cp .env.example .env
# Start with Docker Compose
docker compose up -d
# Access at http://localhost:3000
On first start, open http://localhost:3000/admin and follow the in-browser setup to create your admin account. Full details — the one-time setup token, Docker file permissions, and ARM64 notes — are in First-run setup.
Updating / release channels: set
PICPEAK_CHANNEL(stabledefault, orbeta) in.env, thendocker compose pull && docker compose up -d. See RELEASING.md for the promotion cadence.
Or: one container, no compose file
For a home server, a NAS, or a single small studio, the all-in-one image runs the whole app as one process with SQLite — no compose file, no separate database, no reverse proxy to wire up:
docker run -d --name picpeak -p 3000:3000 \
-v picpeak:/data \
-e JWT_SECRET="$(openssl rand -base64 48)" \
ghcr.io/picpeak/picpeak/aio:stable
Then open http://localhost:3000/admin and read the setup token with docker exec picpeak cat /data/db/SETUP_TOKEN.
The compose stack above is still the right choice for anything busier — SQLite takes one writer at a time, and Postgres is what scales. You can move to it later without reinstalling: take a .picpeak backup and restore it into the full stack. See Single-container install for the volume layout, the external-Postgres variant, TLS, and the limits.
🌟 Why PicPeak?
Unlike expensive SaaS solutions, PicPeak gives you:
- 💰 No Monthly Fees — one-time setup, unlimited galleries
- 🔒 Complete Data Control — your photos stay on your server
- 🎨 White-Label Ready — full branding customization
- 📱 Mobile-First Design — beautiful on all devices
- 🌍 Multi-Language — built-in i18n (EN, DE)
✨ Features
For photographers — drag & drop upload, auto-expiring & password-protected galleries, automated emails, an analytics dashboard, custom themes, a public landing page, and a Live Slideshow projector view that auto-picks-up new uploads during live events.
For clients — clean mobile-optimized galleries, one-click bulk downloads, smart search, optional guest uploads, and download protection (watermarking + right-click prevention).
Technical — Docker-ready, automatic thumbnail generation, external media reference mode, smart archiving of expired galleries, S3-compatible storage backends, webhooks, and security-first defaults (JWT, rate limiting, CORS).
🧾 For studios — CRM & Accounting (Beta, off by default)
- 📝 Quotes → Contracts → Invoices — one deal lineage; cancel-and-reissue (Storno) keeps issued invoices immutable
- ⏱️ Hours Logging & Calendar — per-customer time tracking; admin calendar of events, logged hours, and pending quotes/contracts
- 🧾 Inbound Supplier Invoices & Expenses — capture received invoices (upload/camera, rasterised server-side), categorise, and re-bill costs to clients
- 📊 Tax Report & Accountant Export — period-scoped income/cost report with VAT breakdown; PDF/CSV plus a Treuhänder/Banana (Swiss/LI) journal export
- 🌍 VAT & Multi-currency — single VAT-code registry snapshotted onto each document
Warning
CRM & Accounting — examples only, verify locally. Feature-flagged off by default. Seeded contract blocks are written by the maintainer, not a lawyer; QR-bills/SEPA payloads and every tax, VAT and Treuhänder/Banana figure are computed from your input and defaults and are jurisdiction-specific guidance only. Have your lawyer review contracts, scan a test QR with your bank's app, and verify all numbers with your accountant / Treuhänder / tax authority before customer-facing use. Read the CRM disclaimers first.
📖 Documentation
Full documentation lives at docs.picpeak.app — deployment, admin settings, API, branding, and more.
| Topic | Link |
|---|---|
| 🚀 Deployment (Docker, env, reverse proxy, SSL) | docs.picpeak.app/deployment |
📦 Single-container install (one docker run, SQLite) |
docs.picpeak.app/deployment/single-container |
| ⚙️ Admin settings reference | docs.picpeak.app/guides/admin-settings |
| 🎯 Creating events | docs.picpeak.app/guides/creating-events |
| 📽️ Live Slideshow | docs.picpeak.app/features/live-slideshow |
| 💾 Backup & Restore | docs.picpeak.app/guides/backup-restore |
| 🔌 API reference | docs.picpeak.app/api |
| 🪝 Webhooks | docs.picpeak.app/features/webhooks |
| 💾 Storage backends (local / S3) | docs.picpeak.app/features/storage-backends |
| 💻 System requirements & tuning | docs.picpeak.app/deployment/system-requirements |
| 🧾 CRM & Accounting | docs.picpeak.app/features/crm · disclaimers |
| 🗺️ Roadmap | GitHub Issues |
Project meta: Contributing · License · Security · Code of Conduct
📊 Comparison with Alternatives
| Feature | PicPeak | PicDrop | Scrapbook.de | Pixieset |
|---|---|---|---|---|
| Self-Hosted | ✅ | ❌ | ❌ | ❌ |
| Custom Branding | ✅ Full | Limited | Limited | ✅ (paid) |
| Monthly Cost | $0* | $29-199 | €19-99 | ~$60 |
| Storage Limit | Unlimited** | 50-500GB | 100-1000GB | 3GB–Unlimited*** |
| Client Uploads | ✅ | ✅ | ✅ | Limited |
| API Access | ✅ | Paid | ❌ | ❌ |
| Open Source | ✅ | ❌ | ❌ | ❌ |
| Customer Accounts | ✅ | ❌ | ❌ | ✅ |
| Quotes / Contracts / Invoices | 🧪 Beta | ❌ | ❌ | ✅ |
| Incoming Invoices & Accounting | 🧪 Beta | ❌ | ❌ | ❌ |
*You bring your own server and, optionally, a domain. **Limited only by your server storage. ***Pixieset's "unlimited" is photos only; video is capped by plan. 🧪 Beta = built but feature-flagged off by default.
🏗️ Tech Stack
- Backend: Node.js, Express, SQLite/PostgreSQL
- Frontend: React, Tailwind CSS, Framer Motion
- Storage: Local filesystem (default) or S3-compatible object store (AWS S3, MinIO, R2, B2, Wasabi, Spaces) — see Storage Backends
- Email: SMTP with customizable templates
- Analytics: Privacy-focused with Umami integration
- External media: point PicPeak at
EXTERNAL_MEDIA_ROOTto reference existing originals read-only, index quickly, and generate thumbnails on demand
📸 Screenshots
Click to see the admin dashboard, analytics, and event management
🎛️ Admin Dashboard
📊 Analytics & Insights
📁 Event Management
🤝 Contributing
We love contributions! PicPeak is built by photographers, for photographers — whether you're fixing bugs, adding features, or improving docs. See the Contributing Guide to get started.
Found a security issue? Please open a security issue. See SECURITY.md for the policy.
☕ Support the Project
PicPeak is free, open source, and self-hostable forever. If it saves you time or replaces a paid subscription, consider buying me a coffee — it directly funds new features, bug fixes, and keeping the demo + docs running. You can also ⭐ star the repo, share it, file good bug reports, or open a PR.
🙏 Acknowledgments
PicPeak is inspired by the best features of commercial platforms while remaining completely open source. It's developed with AI assistance, but human-tested end-to-end, security-audited, and human-reviewed for quality.
👥 Contributors
A huge thank you to the people whose code, reports, and feedback have shaped PicPeak:
@the-luap — creator and lead maintainer
- Gallery foundation (events, uploads, sharing, download protection, templates)
- Backup & restore, analytics, branding/theming
- The architecture every later feature builds on
- Native Apple Silicon multi-arch images
- CRM & accounting suite (quotes/contracts/invoices)
- Hours logging & Treuhänder/Banana tax export
- Gallery header/banner decoupling
@Rekoo-PS — bug reports & product feedback
- Login-loop fix, mobile-lightbox overhaul, bulk-delete workflow
- Also a BuyMeACoffee supporter
If you've contributed and aren't listed here, please open a PR — this list is meant to grow.
📄 License
PicPeak is released under the MIT License. Use it freely for personal or commercial projects.
Made with ❤️ by photographers, for photographers
Homepage ·
Live Demo ·
Documentation ·
Support