picpeak/SETUP_GUIDE.md

🚀 PicPeak Beta Setup Guide

This guide helps non-technical users install PicPeak on Raspberry Pi or VPS systems using the automated setup script.

📋 Quick Setup

Step 1: Download and Run Setup Script

# Download PicPeak
wget -O setup-picpeak.sh https://raw.githubusercontent.com/the-luap/picpeak/main/setup-picpeak.sh

# Make it executable
chmod +x setup-picpeak.sh

# Run the setup
bash setup-picpeak.sh

Or in one command:

curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/setup-picpeak.sh | bash

Step 2: Follow the Interactive Prompts

The script will guide you through:

1. ✅ System requirements check
2. 🐋 Docker installation (if needed)
3. 🌐 Domain/IP configuration
4. 📧 Email setup (optional)
5. 🔐 Automatic password generation
6. 📦 PicPeak download and configuration
7. 🚀 Service startup

📋 Prerequisites

Minimum System Requirements

• OS: Ubuntu, Debian, Raspberry Pi OS, CentOS, or Fedora
• RAM: 2GB minimum (script will warn if less)
• Storage: 20GB free space minimum
• Network: Internet connection for downloads

Supported Systems

• ✅ Ubuntu 20.04+
• ✅ Debian 11+
• ✅ Raspberry Pi OS (32-bit and 64-bit)
• ✅ CentOS 7+
• ✅ Fedora 30+

🛠️ What the Script Does

Automatic Installation

1. System Check: Verifies RAM, disk space, and architecture
2. Docker Setup: Installs Docker and Docker Compose if missing
3. Network Configuration: Helps configure domain/IP access
4. Email Configuration: Optional setup for Gmail, SendGrid, or custom SMTP
5. Security: Generates secure passwords automatically
6. Service Deployment: Downloads, builds, and starts PicPeak
7. SSL Support: Optional Let's Encrypt SSL setup

Generated Configurations

• Secure JWT secret (64 hex characters)
• Database password (PostgreSQL)
• Redis password
• Environment configuration file
• Docker Compose setup

🌐 Network Configuration Options

1. Local Network Access (Default)

• Uses your local IP address
• Accessible only on your local network
• Perfect for home/office use

2. Public IP Access

• Uses your server's public IP
• Accessible from the internet
• Requires firewall configuration

3. Domain Name

• Uses your custom domain (e.g., photos.mydomain.com)
• Supports SSL/HTTPS with Let's Encrypt
• Professional setup

4. Development Mode

• Uses localhost
• Only accessible from the same machine
• Good for testing

📧 Email Configuration

Gmail (Recommended for Beginners)

1. Enable 2-Factor Authentication on your Google account
2. Generate an App Password for PicPeak
3. Use your Gmail address and the App Password

SendGrid (Recommended for Production)

1. Sign up at sendgrid.com (free tier: 100 emails/day)
2. Create an API key
3. Verify your sender email address

Custom SMTP

• Use any SMTP server
• Configure host, port, security, and credentials

Skip Email Setup

• Configure later in the admin panel
• PicPeak works without email but notifications won't be sent

🔐 Security Features

Automatic Password Generation

• JWT secret: 64 hex characters
• Database password: 32 base64 characters (no $ symbols)
• Redis password: 32 base64 characters (no $ symbols)

First Login Security

• Auto-generated admin password shown in setup
• Mandatory password change on first login
• Strong password requirements enforced

SSL/HTTPS Support

• Optional Let's Encrypt integration
• Automatic nginx reverse proxy setup
• Forced HTTPS redirects

📍 Access Information

After successful installation, you'll get:

Access URLs

• Gallery: http://your-domain:3000 (or https://your-domain with SSL)
• Admin Panel: http://your-domain:3001/admin (or https://your-domain/admin with SSL)

Admin Credentials

• Email: admin@example.com
• Password: Auto-generated (shown during setup)

🚨 Important First Steps

1. Change Admin Password

• The password change is mandatory for security
• You cannot skip this step
• New password requirements:
  • Minimum 12 characters
  • Mixed case letters
  • Numbers and special characters

2. Configure Email (if skipped)

1. Login to admin panel
2. Go to Settings → Email Configuration
3. Enter your SMTP details
4. Test email sending

3. Create Your First Gallery

1. Go to Admin Panel → Events
2. Click "Create New Event"
3. Upload photos to the generated folders
4. Share the gallery URL and password

🛠️ Management Commands

Service Management

# View logs
cd ~/picpeak && docker compose logs -f

# Stop services
cd ~/picpeak && docker compose down

# Start services
cd ~/picpeak && docker compose up -d

# Restart services
cd ~/picpeak && docker compose restart

Admin Password Reset

# Reset admin password
docker exec picpeak-backend node scripts/show-admin-credentials.js --reset

Updates

cd ~/picpeak
git pull
docker compose down
docker compose build
docker compose up -d

🐛 Troubleshooting

Common Issues

"Permission denied" when running script

chmod +x setup-picpeak.sh

"Docker command not found" after installation

# Log out and back in, or run:
newgrp docker

Can't access web interface

1. Check if services are running: docker compose ps
2. Check firewall: sudo ufw allow 3000 and sudo ufw allow 3001
3. Verify URLs in browser match the setup configuration

502 Bad Gateway

1. Wait 60 seconds for services to fully start
2. Check backend logs: docker compose logs backend
3. Restart frontend: docker restart picpeak-frontend

Email not working

1. Verify SMTP settings in admin panel
2. Check email queue: Admin Panel → Settings → Email
3. Test with a simple service like Gmail first

Getting Help

1. Check the logs: docker compose logs -f
2. Review this guide and the main deployment guide
3. Search existing GitHub issues
4. Create a new issue with:
   • Error messages
   • System information (uname -a)
   • Setup choices made

📁 File Locations

After installation:

• Installation directory: ~/picpeak
• Photos: ~/picpeak/storage/events/
• Logs: ~/picpeak/logs/
• Database: Docker volume picpeak_postgres-data
• Backups: ~/picpeak/backup/

🔒 Security Recommendations

For Internet-Facing Installations

1. Use HTTPS: Enable SSL during setup
2. Firewall: Only open ports 80 and 443
3. Updates: Keep system and Docker updated
4. Backups: Configure automatic backups in admin panel
5. Monitoring: Regularly check logs for suspicious activity

For Local Network Use

1. Strong passwords: Use the auto-generated passwords
2. Network security: Secure your local network
3. Regular backups: Even for local use
4. Access control: Only share admin credentials with trusted users

🎯 Next Steps

After installation:

1. Complete admin setup (change password)
2. Configure email notifications
3. Create your first test gallery
4. Set up automated backups
5. Customize themes and branding
6. Configure analytics (optional)

📞 Support

• Documentation: Check the main deployment guide
• Issues: GitHub Issues page
• Community: GitHub Discussions
• Updates: Star the repository for notifications

---

PicPeak Beta Setup Script v1.0 - Making photo sharing simple for everyone! 📸