From 64f606152fde2db9034fa9ffa08cc58623edf646 Mon Sep 17 00:00:00 2001 From: Paul Nothaft Date: Wed, 8 Apr 2026 13:14:57 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20rewrite=20README=20=E2=80=94=20shorter,?= =?UTF-8?q?=20cleaner,=20less=20AI-sounding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrote from 350 lines to ~130 lines. Removed emoji-heavy headings, marketing fluff, redundant sections, and the AI disclosure. Collapsed screenshots into details tags. Kept all essential info: demo, features, quick start, comparison, tech stack, docs links. --- README.md | 378 ++++++++++++------------------------------------------ 1 file changed, 85 insertions(+), 293 deletions(-) diff --git a/README.md b/README.md index 0c8357f6..241c97d2 100644 --- a/README.md +++ b/README.md @@ -1,350 +1,142 @@ -# ๐Ÿ“ธ PicPeak - Open Source Photo Sharing for Events +# PicPeak
PicPeak Logo - + + **Self-hosted photo sharing for event photographers.** + [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://www.docker.com/) [![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/) [![React](https://img.shields.io/badge/react-%2320232a.svg?style=flat&logo=react&logoColor=%2361DAFB)](https://reactjs.org/) - [Homepage](https://www.picpeak.app) ยท [Live Demo](https://demo.picpeak.app) ยท [Documentation](DEPLOYMENT_GUIDE.md) + [Live Demo](https://demo.picpeak.app) ยท [Deployment Guide](DEPLOYMENT_GUIDE.md) ยท [Homepage](https://www.picpeak.app)
-**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. +--- + +PicPeak lets you create password-protected, time-limited photo galleries for your clients โ€” hosted on your own server. No subscriptions, no storage limits, no third-party access to your photos. ![PicPeak Gallery Preview](docs/screenshot-gallery.png) -## ๐ŸŽฎ Live Demo +## Demo -Try PicPeak without installing anything: +Try it out at [demo.picpeak.app](https://demo.picpeak.app). -| | | -|---|---| -| **Demo URL** | [demo.picpeak.app](https://demo.picpeak.app) | -| **Admin Panel** | [demo.picpeak.app/admin](https://demo.picpeak.app/admin) | -| **Email** | `demo@picpeak.app` | -| **Password** | `Demo2026!` | +Admin panel: [demo.picpeak.app/admin](https://demo.picpeak.app/admin) โ€” login with `demo@picpeak.app` / `Demo2026!` -> The demo resets periodically. Uploaded content may be removed without notice. +> The demo resets periodically. -## ๐ŸŒŸ Why Choose PicPeak? +## Features -Unlike expensive SaaS solutions, PicPeak gives you: +**Gallery Management** โ€” Create galleries, upload photos via drag & drop, set passwords and expiration dates. Galleries auto-archive when they expire. Events start as drafts so you can upload and prepare before notifying the client. -- **๐Ÿ’ฐ 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) +**Client Experience** โ€” Responsive galleries that look great on any device. Guests can browse, download individual photos or everything at once. Optional guest uploads and feedback (likes, comments, ratings). -## โœจ Key Features +**Themes & Branding** โ€” 11 built-in theme presets, custom CSS templates, configurable colors/fonts/layouts. White-label your admin panel and login page with your own logo and company name. -### 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 +**Email Notifications** โ€” Automated gallery creation, expiration warning, and archive emails. Multilingual templates (EN, DE, NL, PT, RU) editable from the admin UI. -### 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 +**Photo Protection** โ€” Watermarking, right-click prevention, canvas rendering, DevTools detection. Configurable per gallery. -### 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 +**External Media** โ€” Reference photos from a mounted folder instead of uploading. PicPeak reads originals in place and generates thumbnails on demand. -## ๐Ÿš€ Quick Start +**Multi-Language** โ€” Full UI translations for English, German, Dutch, Portuguese, and Russian. Email templates support all languages independently. -Get PicPeak running in under 5 minutes: +**Analytics** โ€” Built-in view/download tracking plus optional Umami integration for privacy-focused analytics. + +**Video Support** โ€” Upload and stream MP4, WebM, MOV alongside photos. FFmpeg bundled via npm. + +**Multiple Admins** โ€” Role-based access control with super admin, admin, and editor roles. + +## Quick Start ```bash -# 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 +# Edit .env โ€” set at least JWT_SECRET and passwords 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". +Open `http://localhost:3000` and log in with the credentials from your `.env`. -## ๐Ÿ”„ Release Channels +> **Permissions:** Set `PUID` and `PGID` in `.env` to match your host user (`id -u` / `id -g`) so Docker volumes are writable. -PicPeak offers two release channels for different needs: +See the [Deployment Guide](DEPLOYMENT_GUIDE.md) for reverse proxy setup, SSL, external media, and production configuration. -### Stable Channel (Recommended) -- Production-ready releases -- Thoroughly tested before release -- Docker tags: `stable`, `latest`, or specific version like `v2.3.0` +## Screenshots -### 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` +
+Admin Dashboard -### Switching Channels +Admin Dashboard +
-Set the `PICPEAK_CHANNEL` environment variable in your `.env` file: +
+Event Management + +Event Management +
+ +
+Analytics + +Analytics +
+ +## Comparison + +| | PicPeak | PicDrop | Scrapbook.de | +|---|---|---|---| +| Self-hosted | Yes | No | No | +| Monthly cost | $0 | $29-199 | 19-99 EUR | +| Storage | Unlimited | 50-500 GB | 100-1000 GB | +| Custom branding | Full | Limited | Limited | +| Open source | Yes | No | No | +| API | Yes | Paid | No | + +## Tech Stack + +- **Backend:** Node.js, Express, PostgreSQL (or SQLite) +- **Frontend:** React, TypeScript, Tailwind CSS +- **Infrastructure:** Docker, Nginx, Redis +- **Processing:** Sharp (images), FFmpeg (video) + +## Release Channels + +**Stable** (`stable` / `latest`) โ€” Production-ready. Use this for real deployments. + +**Beta** (`beta`) โ€” Early access to new features. May have rough edges. ```bash -# For stable releases (default) -PICPEAK_CHANNEL=stable +# Set in .env +PICPEAK_CHANNEL=stable # or beta -# For beta releases -PICPEAK_CHANNEL=beta - -# For a specific version -PICPEAK_CHANNEL=v2.3.0 -``` - -Then update your containers: - -```bash +# Update docker compose -f docker-compose.production.yml pull docker compose -f docker-compose.production.yml up -d ``` -### Update Notifications +The admin dashboard notifies you when updates are available. -The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set: +## Contributing -```bash -UPDATE_CHECK_ENABLED=false -``` +We welcome contributions โ€” bug fixes, features, translations, documentation. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions. -## ๐Ÿ“– Documentation +## Documentation -- ๐Ÿ“˜ [**Deployment Guide**](DEPLOYMENT_GUIDE.md) - Detailed installation instructions - - Includes the new [External Media Library](DEPLOYMENT_GUIDE.md#external-media-library) reference mode -- ๐Ÿ“š [**Admin API (OpenAPI)**](docs/picpeak-admin-api.openapi.yaml) - Machine-readable documentation for event automation endpoints -- ๐Ÿ› ๏ธ [**Admin API Quickstart**](docs/admin-api-quickstart.md) - Step-by-step authentication and testing guide for the documented endpoints -- ๐Ÿค [**Contributing**](CONTRIBUTING.md) - How to contribute -- ๐Ÿ“œ [**License**](LICENSE) - MIT License -- ๐Ÿ”’ [**Security**](SECURITY.md) - Security policies -- ๐Ÿ“‹ [**Code of Conduct**](CODE_OF_CONDUCT.md) - Community guidelines +- [Deployment Guide](DEPLOYMENT_GUIDE.md) โ€” Installation, configuration, reverse proxy, external media +- [Admin API (OpenAPI)](docs/picpeak-admin-api.openapi.yaml) โ€” Machine-readable API spec +- [Admin API Quickstart](docs/admin-api-quickstart.md) โ€” Authentication and testing guide +- [Security Policy](SECURITY.md) -## ๐ŸŒ Public Landing Page +## License -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: -```nginx -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](CONTRIBUTING.md) 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](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub - -## ๐Ÿ“ธ Screenshots - -### ๐ŸŽ›๏ธ **Admin Dashboard** -Get a complete overview of your photo galleries, analytics, and system status. - -PicPeak Admin Dashboard - -### ๐Ÿ“Š **Analytics & Insights** -Track gallery performance, view statistics, and monitor user engagement. - -PicPeak Analytics Dashboard - -### ๐Ÿ“ **Event Management** -Organize and manage your photo galleries with intuitive event management tools. - -PicPeak Events Management - -### โœจ **Key Interface Highlights** - -
-๐Ÿ‘† Click to see more interface details - -#### What makes PicPeak's interface special: - -- **๐ŸŽจ Clean Design**: Modern, photographer-friendly interface -- **๐Ÿ“ฑ Responsive**: Perfect on desktop, tablet, and mobile -- **โšก Fast Loading**: Optimized for quick photo browsing -- **๐Ÿ”’ Secure Access**: Password-protected galleries with expiration -- **๐Ÿ“ค Easy Uploads**: Drag & drop functionality for effortless photo management -- **๐ŸŽฏ Client-Focused**: Intuitive gallery experience for your clients - -
- -## ๐Ÿ—บ๏ธ Roadmap - -We're constantly improving PicPeak and welcome contributions from our community! If you have ideas for new features or want to help implement existing ones, please open an issue or submit a pull request. Your contributions help make PicPeak better for everyone. - -### ๐Ÿšง Beta Features (Use at your own risk) - -These features are currently in beta testing and may have limited functionality or stability: - -| Feature | Description | Status | -|---------|-------------|--------| -| **Simple Deployment Script** | One-click deployment script for quick server setup with automated configuration and dependency installation | ๐Ÿงช Beta | - -### ๐Ÿ“‹ Future Enhancements - -| Feature | Description | Priority | Status | -|---------|-------------|----------|---------| -| **Backup & Restore** | Comprehensive backup system with S3/MinIO support, automated scheduling, and safe restore functionality | High | โœ… Implemented | -| **External Media Library (Reference Mode)** | Use an external folder library as a readโ€‘only source with import and onโ€‘demand thumbnail generation | High | โœ… Implemented | -| **Download Protection** | Advanced image protection system with canvas rendering, invisible watermarking, right-click prevention, and DevTools detection to protect photos from unauthorized downloads | High | โœ… Implemented | -| **Gallery Templates** | Multiple gallery layouts (grid, masonry, carousel, timeline, hero, mosaic) with custom CSS styling support. Includes starter templates like Apple Liquid Glass for complete visual customization | Medium | โœ… Implemented | -| **Face Recognition** | AI-powered face detection to help guests find their photos and create automatic person-based albums | Low | ๐Ÿ”„ Open | -| **Gallery Feedback** | Allow guests to like, rate, and comment on photos with admin notifications and moderation | Medium | โœ… Implemented | -| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | Low | โœ… Implemented | -| **Multiple Administrators** | Support for multiple admin accounts with role-based permissions and activity tracking | Low | โœ… Implemented | -| **Filtering & Export Options** | Filter photos by likes, ratings, comments, or favorites. Search by filename. Sort by date, name, size, or rating. Export filtered selections as ZIP or generate Capture One/Lightroom-compatible file lists for professional workflows | Medium | โœ… Implemented | - -**Status Legend:** โœ… Implemented | ๐Ÿšง In Progress | ๐Ÿ”„ Open | ๐Ÿ“‹ Planned - -## ๐Ÿ™ Acknowledgments - -PicPeak is inspired by the best features of commercial platforms while remaining completely open source. Special thanks to all contributors who make this project possible. - -### ๐Ÿค– AI-Assisted Development - -This project was generated with the assistance of AI technology, but has been: -- โœ… **Fully tested end-to-end** by human developers -- ๐Ÿ”’ **Security audited** with comprehensive security checks -- ๐Ÿ‘จโ€๐Ÿ’ป **Human-reviewed** for code quality and best practices -- ๐Ÿงช **Production-tested** in real-world scenarios - -We believe in transparent development practices and the responsible use of AI as a tool to accelerate development while maintaining high standards of quality and security. - -## ๐Ÿ“„ License - -PicPeak is released under the [MIT License](LICENSE). Use it freely for personal or commercial projects. - -## ๐Ÿš€ Ready to Get Started? - -1. โญ **Star this repository** to show your support -2. ๐Ÿ“– Read the [Deployment Guide](DEPLOYMENT_GUIDE.md) -3. ๐Ÿ› Report issues or request features -4. ๐Ÿค Join our community and contribute! +MIT โ€” use it for personal or commercial projects. ---

- Made with โค๏ธ by photographers, for photographers -
- Homepage โ€ข - Live Demo โ€ข - GitHub โ€ข - Documentation โ€ข - Support + Homepage ยท Live Demo ยท Docs ยท Issues