📸 PicPeak - Open Source Photo Sharing for Events

<div align="center"> <img src="docs/picpeak-logo.png" alt="PicPeak Logo" width="300" />

Homepage · Live Demo · Documentation

</div>

PicPeak is a powerful, self-hosted open-source alternative to commercial photo-sharing platforms like PicDrop.com and Scrapbook.de. Designed specifically for photographers and event organizers, PicPeak makes it simple to share beautiful, time-limited photo galleries with clients while maintaining full control over your data and branding.

🎮 Live Demo

Try PicPeak without installing anything:

| | | |---|---| | Demo URL | demo.picpeak.app | | Admin Panel | demo.picpeak.app/admin | | Email | demo@picpeak.app | | Password | Demo2026! |

The demo resets periodically. Uploaded content may be removed without notice.

🌟 Why Choose 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
• 🚀 Lightning Fast - Optimized performance and caching
• 🌍 Multi-Language - Built-in i18n support (EN, DE)

✨ Key Features

For Photographers

• 📁 Drag & Drop Upload - Simply drop photos into folders
• 🔗 External Media (Reference Mode) - Browse and import from a read‑only external folder library without copying originals
• ⏰ Auto-Expiring Galleries - Set expiration dates (default: 30 days)
• 🔐 Password Protection - Secure client galleries
• 📧 Automated Emails - Creation confirmations and expiration warnings
• 📊 Analytics Dashboard - Track views, downloads, and engagement
• 🎨 Custom Themes - Match your brand perfectly
• 🌐 Public Landing Page - Publish a curated marketing page when guests visit your root URL

For Clients

• 🖼️ Beautiful Galleries - Clean, modern interface
• 📱 Mobile Optimized - Swipe through photos on any device
• ⬇️ Bulk Downloads - Download all photos with one click
• 🔍 Smart Search - Find photos quickly
• 📤 Guest Uploads - Optional client photo uploads
• 🛡️ Download Protection - Advanced image protection with watermarking and right-click prevention

Technical Excellence

• 🐳 Docker Ready - Deploy in minutes
• 🔄 Auto-Processing - Automatic thumbnail generation
• 🗂️ Reference Library Support - Point PicPeak at EXTERNAL_MEDIA_ROOT to reference existing originals, index quickly, and generate thumbnails on demand
• 💾 Smart Storage - Automatic archiving of expired galleries
• 🛡️ Security First - JWT auth, rate limiting, CORS protection
• 📈 Scalable - From small studios to large agencies

🚀 Quick Start

Get PicPeak running in under 5 minutes:

# Clone the repository
git clone https://github.com/the-luap/picpeak.git
cd picpeak

# Copy environment template
cp .env.example .env

# Edit configuration (required: JWT_SECRET)
nano .env

# Start with Docker Compose
docker compose up -d

# Access at http://localhost:3000

Note on Docker file permissions (PUID/PGID)

• When using bind mounts (e.g., ./storage, ./data, ./logs, ./events), ensure the container user can write to these host folders. The backend runs as a non‑root user by default.
• Set PUID and PGID in your .env to match your host user’s UID/GID (run id -u and id -g on the host). Compose maps the container user to these values.
• Example in .env:
  • PUID=1000
  • PGID=1000
• Without this, creating events, uploads, thumbnails, or logs can fail with "Permission denied".

🔄 Release Channels

PicPeak offers two release channels for different needs:

Stable Channel (Recommended)

• Production-ready releases
• Thoroughly tested before release
• Docker tags: stable, latest, or specific version like v2.3.0

Beta Channel

• Early access to new features
• May contain bugs or incomplete functionality
• Docker tags: beta or specific version like v2.3.0-beta.1

Switching Channels

Set the PICPEAK_CHANNEL environment variable in your .env file:

# For stable releases (default)
PICPEAK_CHANNEL=stable

# For beta releases
PICPEAK_CHANNEL=beta

# For a specific version
PICPEAK_CHANNEL=v2.3.0

Then update your containers:

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

Update Notifications

The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set:

UPDATE_CHECK_ENABLED=false

📖 Documentation

• 📘 Deployment Guide - Detailed installation instructions
  • Includes the new External Media Library reference mode
• 📚 Admin API (OpenAPI) - Machine-readable documentation for event automation endpoints
• 🛠️ Admin API Quickstart - Step-by-step authentication and testing guide for the documented endpoints
• 🤝 Contributing - How to contribute
• 📜 License - MIT License
• 🔒 Security - Security policies
• 📋 Code of Conduct - Community guidelines

🌐 Public Landing Page

Spotlight your studio with a customizable marketing page at /:

• Head to Admin → CMS Pages to enable the public landing page toggle.
• Edit the provided HTML template (rich sections, hero, testimonials) and optional CSS overrides.
• The preview renders in a sandboxed iframe so you can iterate safely before publishing.
• PicPeak sanitizes stored HTML and CSS server-side—scripts, iframes, and unsafe attributes are stripped automatically.
• Use Reset to default anytime to restore the bundled template.
• The backend caches the rendered landing page for 60 seconds by default; override with PUBLIC_SITE_CACHE_TTL_MS if you need a different TTL.
• When the landing page is disabled PicPeak continues to serve the admin SPA/login exactly as before.

🎯 Use Cases

Perfect for:

• 💒 Wedding Photographers - Share ceremony photos securely
• 🎂 Event Photography - Birthday parties, corporate events
• 📸 Portrait Studios - Client galleries with download limits
• 🏢 Corporate Events - Internal photo sharing with branding
• 🎓 School Photography - Secure parent access with expiration

🏗️ Tech Stack

• Backend: Node.js, Express, SQLite/PostgreSQL
• Frontend: React, Tailwind CSS, Framer Motion
• Storage: File-based with automatic archiving
• Email: SMTP with customizable templates
• Analytics: Privacy-focused with Umami integration

💻 System Requirements

Minimum Requirements

• CPU: 2 CPU cores
• RAM: 2GB minimum
• Storage: 20GB minimum (plus photo storage needs)
• OS: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
• Node.js: v18.0.0 or higher
• Database: SQLite (included) or PostgreSQL 12+

Docker Requirements (Recommended)

• Docker: v20.10.0+
• Docker Compose: v2.0.0+

Video Support Requirements

When enabling video uploads, consider these additional resources:

| Resource | Recommendation | Notes | |----------|----------------|-------| | RAM | 4GB+ recommended | FFmpeg processing requires more memory | | Storage | Plan for 10-100x 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: 10GB per video file
• Chunked upload support for files >100MB (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;

🤝 Contributing

We love contributions! PicPeak is built by photographers, for photographers. Whether you're fixing bugs, adding features, or improving documentation, your help is welcome.

See our Contributing Guide for details.

📊 Comparison with Alternatives

| Feature | PicPeak | PicDrop | Scrapbook.de | |---------|---------|---------|--------------| | Self-Hosted | ✅ | ❌ | ❌ | | Custom Branding | ✅ Full | Limited | Limited | | Monthly Cost | $0 | $29-199 | €19-99 | | Storage Limit | Unlimited* | 50-500GB | 100-1000GB | | Client Uploads | ✅ | ✅ | ✅ | | API Access | ✅ | Paid | ❌ | | Open Source | ✅ | ❌ | ❌ |

*Limited only by your server storage

🛡️ Security

PicPeak takes security seriously:

• 🔐 Password hashing with bcrypt
• 🎫 JWT-based authentication
• 🚦 Rate limiting on all endpoints
• 🛡️ CORS protection
• 📝 Activity logging
• 🔒 Secure file access

Found a security issue? Please open a security issue on GitHub

📸 Screenshots

🎛️ Admin Dashboard

Get a comp