# PicPeak Deployment Guide

This guide covers deploying PicPeak for development and production environments.

## Table of Contents
- [Quick Start (Development)](#quick-start-development)
- [Production Deployment](#production-deployment)
- [Admin User Setup](#admin-user-setup)
- [Configuration Reference](#configuration-reference)
- [Troubleshooting](#troubleshooting)

## Quick Start (Development)

### 1. Clone and Setup

```bash
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

```bash
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

```bash
# 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:

```env
# 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

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

### 3. Deploy with Docker Compose

```bash
# 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`:

```yaml
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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Logs

```bash
# 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:
   ```bash
   docker-compose -f docker-compose.prod.yml logs db
   ```

2. Verify environment variables:
   ```bash
   docker-compose -f docker-compose.prod.yml exec backend env | grep DB_
   ```

### Can't Login as Admin

1. Verify admin user exists:
   ```bash
   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:
   ```bash
   # 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:
   ```bash
   ls -la ./storage/events/active/
   ```

2. Verify nginx proxy configuration:
   ```bash
   docker-compose -f docker-compose.prod.yml exec frontend \
     cat /etc/nginx/conf.d/default.conf
   ```

### Email Not Sending

1. Check email configuration:
   ```bash
   docker-compose -f docker-compose.prod.yml exec backend env | grep SMTP_
   ```

2. View email queue:
   ```bash
   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

```bash
# 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

```bash
# 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