picpeak/DEPLOYMENT.md

PicPeak Deployment Guide

This guide covers deploying PicPeak for development and production environments.

Table of Contents

• Quick Start (Development)
• Production Deployment
• Admin User Setup
• Configuration Reference
• Troubleshooting

Quick Start (Development)

1. Clone and Setup

git clone https://github.com/yourusername/picpeak.git
cd picpeak

# Copy environment template
cp .env.example .env

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

2. Access Services

• Frontend: http://localhost:3005
• Backend API: http://localhost:3001
• MailHog (email testing): http://localhost:8025

3. Create Admin User

docker-compose -f docker-compose.dev.yml exec backend node scripts/create-admin.js \
  --email admin@localhost \
  --username admin \
  --password admin123

Production Deployment

Prerequisites

• Docker and Docker Compose installed
• Domain with DNS configured
• SSL/TLS handled by reverse proxy (Traefik, Nginx, etc.)

1. Environment Setup

# Copy production template
cp .env.production.example .env

# Generate secure secrets
echo "JWT_SECRET=$(openssl rand -base64 32)" >> .env
echo "DB_PASSWORD=$(openssl rand -base64 24)" >> .env

Edit .env with your configuration:

# Your domain
ADMIN_URL=https://yourdomain.com
FRONTEND_URL=https://yourdomain.com

# Database (PostgreSQL)
DB_USER=picpeak
DB_NAME=picpeak
# DB_PASSWORD already generated above

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=true
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
EMAIL_FROM=noreply@yourdomain.com

2. Frontend Configuration

# Configure frontend for production
echo "VITE_API_URL=/api" > frontend/.env.production

3. Deploy with Docker Compose

# Build and start services
docker-compose -f docker-compose.prod.yml up -d

# Check status
docker-compose -f docker-compose.prod.yml ps

# View logs
docker-compose -f docker-compose.prod.yml logs -f

4. Deploy with Traefik

If using Traefik, create docker-compose.override.yml:

version: '3.8'

services:
  frontend:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.picpeak.rule=Host(`yourdomain.com`)"
      - "traefik.http.routers.picpeak.entrypoints=websecure"
      - "traefik.http.routers.picpeak.tls.certresolver=letsencrypt"
      - "traefik.http.services.picpeak.loadbalancer.server.port=80"
    networks:
      - traefik
      - picpeak

networks:
  traefik:
    external: true

Admin User Setup

Create First Admin

After deployment, create your admin user:

# Production
docker-compose -f docker-compose.prod.yml exec backend node scripts/create-admin.js \
  --email admin@yourdomain.com \
  --username admin \
  --password yourSecurePassword

# Auto-generate password
docker-compose -f docker-compose.prod.yml exec backend node scripts/create-admin.js \
  --email admin@yourdomain.com

The script will display:

• ✅ Admin user created successfully!
• Email: admin@yourdomain.com
• Username: admin
• Login URL: https://yourdomain.com/admin/login
• Password: (save this if auto-generated!)

Managing Admin Users

# List admin users
docker-compose -f docker-compose.prod.yml exec backend \
  psql postgresql://picpeak:$DB_PASSWORD@db:5432/picpeak \
  -c "SELECT id, username, email, is_active, last_login FROM admin_users;"

# Deactivate user
docker-compose -f docker-compose.prod.yml exec backend \
  psql postgresql://picpeak:$DB_PASSWORD@db:5432/picpeak \
  -c "UPDATE admin_users SET is_active = false WHERE email = 'user@example.com';"

Configuration Reference

Database Configuration

PicPeak automatically detects the environment and uses:

• Development: SQLite (./data/photo_sharing.db)
• Production: PostgreSQL (configured via environment variables)

Environment Variables

Required for Production

Variable	Description	Example
JWT_SECRET	JWT signing key	openssl rand -base64 32
DB_PASSWORD	PostgreSQL password	openssl rand -base64 24
ADMIN_URL	Admin panel URL	https://yourdomain.com
FRONTEND_URL	Frontend URL	https://yourdomain.com
EMAIL_FROM	Sender email	noreply@yourdomain.com

Email Configuration

Variable	Description	Example
SMTP_HOST	SMTP server	smtp.gmail.com
SMTP_PORT	SMTP port	587
SMTP_SECURE	Use TLS	true
SMTP_USER	SMTP username	your-email@gmail.com
SMTP_PASS	SMTP password	App-specific password

Storage Paths

• Photos: ./storage/events/active/
• Archives: ./storage/events/archived/
• Thumbnails: ./storage/thumbnails/
• Uploads: ./storage/uploads/

Backup and Restore

Backup Database

# PostgreSQL backup
docker-compose -f docker-compose.prod.yml exec db \
  pg_dump -U picpeak picpeak > backup-$(date +%Y%m%d).sql

# Backup storage
tar -czf storage-backup-$(date +%Y%m%d).tar.gz ./storage

Restore Database

# PostgreSQL restore
docker-compose -f docker-compose.prod.yml exec -T db \
  psql -U picpeak picpeak < backup-20240115.sql

# Restore storage
tar -xzf storage-backup-20240115.tar.gz

Monitoring

Health Checks

# Backend health
curl https://yourdomain.com/api/health

# Frontend health
curl https://yourdomain.com/health

Logs

# All services
docker-compose -f docker-compose.prod.yml logs -f

# Specific service
docker-compose -f docker-compose.prod.yml logs -f backend

# Last 100 lines
docker-compose -f docker-compose.prod.yml logs --tail=100 backend

Troubleshooting

Backend Won't Start

1. Check database connection:

   docker-compose -f docker-compose.prod.yml logs db
   

2. Verify environment variables:

   docker-compose -f docker-compose.prod.yml exec backend env | grep DB_
   

Can't Login as Admin

1. Verify admin user exists:

   docker-compose -f docker-compose.prod.yml exec backend \
     psql postgresql://picpeak:$DB_PASSWORD@db:5432/picpeak \
     -c "SELECT * FROM admin_users;"
   

2. Reset admin password:

   # Create new admin with different email
   docker-compose -f docker-compose.prod.yml exec backend \
     node scripts/create-admin.js --email newadmin@yourdomain.com
   

Photos Not Loading

1. Check file permissions:

   ls -la ./storage/events/active/
   

2. Verify nginx proxy configuration:

   docker-compose -f docker-compose.prod.yml exec frontend \
     cat /etc/nginx/conf.d/default.conf
   

Email Not Sending

1. Check email configuration:

   docker-compose -f docker-compose.prod.yml exec backend env | grep SMTP_
   

2. View email queue:

   docker-compose -f docker-compose.prod.yml exec backend \
     psql postgresql://picpeak:$DB_PASSWORD@db:5432/picpeak \
     -c "SELECT * FROM email_queue WHERE status = 'failed';"
   

Maintenance

Update Application

# Pull latest changes
git pull

# Rebuild images
docker-compose -f docker-compose.prod.yml build

# Restart services
docker-compose -f docker-compose.prod.yml up -d

Clean Up

# Remove unused images
docker image prune -a

# Clean up logs
docker-compose -f docker-compose.prod.yml logs --tail=0 -f

# Remove old archives
find ./storage/events/archived -name "*.zip" -mtime +90 -delete

Security Checklist

• Generated secure JWT_SECRET
• Generated secure DB_PASSWORD
• HTTPS enabled via reverse proxy
• Changed default admin credentials
• Configured real SMTP server
• Set file permissions: chmod 600 .env
• Firewall configured
• Regular backups scheduled
• Monitoring enabled