From 2c9a56f217218f0700817d150b3de115e9503baa Mon Sep 17 00:00:00 2001 From: paul Date: Fri, 29 Aug 2025 22:22:40 +0200 Subject: [PATCH] docs: update deployment guide with GitHub Container Registry images MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added instructions for using pre-built images from ghcr.io - Created docker-compose.production.yml for quick deployment with official images - Updated deployment guide with two methods: 1. Using pre-built images (fastest, recommended) 2. Building from source (for customization) - Updated SIMPLE_SETUP references to use new unified script - Added specific version deployment instructions - Maintained backward compatibility with local build process The pre-built images eliminate build time and ensure consistent deployments across environments. Users can now deploy PicPeak in minutes using: - ghcr.io/the-luap/picpeak/backend:latest - ghcr.io/the-luap/picpeak/frontend:latest 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude-flow/metrics/system-metrics.json | 168 +++++++++++++++++++++++ DEPLOYMENT_GUIDE.md | 141 +++++++++++++++++-- docker-compose.production.yml | 113 +++++++++++++++ 3 files changed, 412 insertions(+), 10 deletions(-) create mode 100644 docker-compose.production.yml diff --git a/.claude-flow/metrics/system-metrics.json b/.claude-flow/metrics/system-metrics.json index a35afd0..c42207d 100644 --- a/.claude-flow/metrics/system-metrics.json +++ b/.claude-flow/metrics/system-metrics.json @@ -718,5 +718,173 @@ "cpuLoad": 0.15691266741071427, "platform": "darwin", "uptime": 5184670 + }, + { + "timestamp": 1756498546659, + "memoryTotal": 25769803776, + "memoryUsed": 25206210560, + "memoryFree": 563593216, + "memoryUsagePercent": 97.81297047932944, + "memoryEfficiency": 2.1870295206705634, + "cpuCount": 14, + "cpuLoad": 0.11258370535714286, + "platform": "darwin", + "uptime": 5184700 + }, + { + "timestamp": 1756498576659, + "memoryTotal": 25769803776, + "memoryUsed": 25285951488, + "memoryFree": 483852288, + "memoryUsagePercent": 98.12240600585938, + "memoryEfficiency": 1.877593994140625, + "cpuCount": 14, + "cpuLoad": 0.10041155133928571, + "platform": "darwin", + "uptime": 5184730 + }, + { + "timestamp": 1756498606659, + "memoryTotal": 25769803776, + "memoryUsed": 25606160384, + "memoryFree": 163643392, + "memoryUsagePercent": 99.36498006184897, + "memoryEfficiency": 0.6350199381510322, + "cpuCount": 14, + "cpuLoad": 0.112548828125, + "platform": "darwin", + "uptime": 5184760 + }, + { + "timestamp": 1756498636661, + "memoryTotal": 25769803776, + "memoryUsed": 25347489792, + "memoryFree": 422313984, + "memoryUsagePercent": 98.3612060546875, + "memoryEfficiency": 1.6387939453125, + "cpuCount": 14, + "cpuLoad": 0.10770089285714286, + "platform": "darwin", + "uptime": 5184790 + }, + { + "timestamp": 1756498666662, + "memoryTotal": 25769803776, + "memoryUsed": 25341689856, + "memoryFree": 428113920, + "memoryUsagePercent": 98.33869934082031, + "memoryEfficiency": 1.6613006591796875, + "cpuCount": 14, + "cpuLoad": 0.10438755580357142, + "platform": "darwin", + "uptime": 5184820 + }, + { + "timestamp": 1756498696663, + "memoryTotal": 25769803776, + "memoryUsed": 25422659584, + "memoryFree": 347144192, + "memoryUsagePercent": 98.65290323893228, + "memoryEfficiency": 1.3470967610677178, + "cpuCount": 14, + "cpuLoad": 0.13065011160714285, + "platform": "darwin", + "uptime": 5184850 + }, + { + "timestamp": 1756498726664, + "memoryTotal": 25769803776, + "memoryUsed": 25604161536, + "memoryFree": 165642240, + "memoryUsagePercent": 99.35722351074219, + "memoryEfficiency": 0.6427764892578125, + "cpuCount": 14, + "cpuLoad": 0.1640625, + "platform": "darwin", + "uptime": 5184880 + }, + { + "timestamp": 1756498756665, + "memoryTotal": 25769803776, + "memoryUsed": 25435848704, + "memoryFree": 333955072, + "memoryUsagePercent": 98.70408376057944, + "memoryEfficiency": 1.2959162394205634, + "cpuCount": 14, + "cpuLoad": 0.14121791294642858, + "platform": "darwin", + "uptime": 5184910 + }, + { + "timestamp": 1756498786666, + "memoryTotal": 25769803776, + "memoryUsed": 25589825536, + "memoryFree": 179978240, + "memoryUsagePercent": 99.30159250895181, + "memoryEfficiency": 0.6984074910481866, + "cpuCount": 14, + "cpuLoad": 0.13194056919642858, + "platform": "darwin", + "uptime": 5184940 + }, + { + "timestamp": 1756498816668, + "memoryTotal": 25769803776, + "memoryUsed": 25063342080, + "memoryFree": 706461696, + "memoryUsagePercent": 97.2585678100586, + "memoryEfficiency": 2.7414321899414062, + "cpuCount": 14, + "cpuLoad": 0.126708984375, + "platform": "darwin", + "uptime": 5184970 + }, + { + "timestamp": 1756498846669, + "memoryTotal": 25769803776, + "memoryUsed": 25080020992, + "memoryFree": 689782784, + "memoryUsagePercent": 97.32329050699869, + "memoryEfficiency": 2.6767094930013116, + "cpuCount": 14, + "cpuLoad": 0.14226422991071427, + "platform": "darwin", + "uptime": 5185000 + }, + { + "timestamp": 1756498876670, + "memoryTotal": 25769803776, + "memoryUsed": 25174196224, + "memoryFree": 595607552, + "memoryUsagePercent": 97.68873850504556, + "memoryEfficiency": 2.3112614949544366, + "cpuCount": 14, + "cpuLoad": 0.15816824776785715, + "platform": "darwin", + "uptime": 5185030 + }, + { + "timestamp": 1756498906670, + "memoryTotal": 25769803776, + "memoryUsed": 25345097728, + "memoryFree": 424706048, + "memoryUsagePercent": 98.35192362467447, + "memoryEfficiency": 1.6480763753255303, + "cpuCount": 14, + "cpuLoad": 0.16050502232142858, + "platform": "darwin", + "uptime": 5185060 + }, + { + "timestamp": 1756498936671, + "memoryTotal": 25769803776, + "memoryUsed": 25402982400, + "memoryFree": 366821376, + "memoryUsagePercent": 98.57654571533203, + "memoryEfficiency": 1.4234542846679688, + "cpuCount": 14, + "cpuLoad": 0.12852260044642858, + "platform": "darwin", + "uptime": 5185090 } ] \ No newline at end of file diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md index bddc24e..4d28baa 100644 --- a/DEPLOYMENT_GUIDE.md +++ b/DEPLOYMENT_GUIDE.md @@ -4,27 +4,62 @@ This guide covers multiple deployment options for PicPeak, from simple local set ## 🎯 Quick Start - Simple Setup (Recommended for Beginners) -For the easiest installation without Docker or complex configurations, use our **simple setup script**: +For the easiest installation without Docker or complex configurations, use our **unified setup script**: ```bash -curl -fsSL https://raw.githubusercontent.com/yourusername/wedding-photo-sharing/main/scripts/simple-setup.sh -o setup.sh && \ +curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/setup.sh -o setup.sh && \ chmod +x setup.sh && \ sudo ./setup.sh ``` -This automated script handles everything including OS detection, dependencies, database setup, and service configuration. Perfect for: +This automated script handles everything including: +- Choice between Docker or Native installation +- OS detection and dependency installation +- Database setup and service configuration +- SSL/HTTPS setup (optional) + +Perfect for: - Small to medium deployments - Local or VPS installations -- Users who prefer avoiding Docker complexity +- Users new to server management - Quick testing and evaluation -👉 **See [SIMPLE_SETUP_GUIDE.md](./SIMPLE_SETUP_GUIDE.md) for detailed instructions.** +👉 **See [SIMPLE_SETUP.md](./SIMPLE_SETUP.md) for detailed instructions.** --- ## 🐳 Docker Compose Deployment -This section covers deploying PicPeak using Docker Compose with direct port exposure. For internet-facing deployments, you'll need to add a reverse proxy (nginx, Traefik, Caddy, etc.) for SSL/HTTPS. +### Option 1: Using Pre-built Images (Recommended) + +PicPeak provides official Docker images via GitHub Container Registry for quick deployment without building: + +```bash +# Clone repository for configuration files +git clone https://github.com/the-luap/picpeak.git +cd picpeak + +# Copy and configure environment +cp .env.example .env +nano .env # Edit with your values + +# Use pre-built images deployment +docker compose -f docker-compose.production.yml up -d +``` + +The production compose file uses: +- **Backend**: `ghcr.io/the-luap/picpeak/backend:latest` +- **Frontend**: `ghcr.io/the-luap/picpeak/frontend:latest` + +Available tags: +- `latest` - Latest stable release +- `main` - Latest main branch build +- `develop` - Development branch (may be unstable) +- `v1.0.0` - Specific version tags + +### Option 2: Building from Source + +If you need to customize the application or the pre-built images aren't available, you can build locally: ## 📋 Table of Contents @@ -46,6 +81,38 @@ This section covers deploying PicPeak using Docker Compose with direct port expo ## 🚀 Quick Start +### Method 1: Using Pre-built Images (Fastest) + +1. **Clone the repository for configs** + ```bash + git clone https://github.com/the-luap/picpeak.git + cd picpeak + ``` + +2. **Set up environment** + ```bash + cp .env.example .env + nano .env # Edit with your values + ``` + +3. **Create required directories** + ```bash + mkdir -p events/active events/archived data logs backup storage + chmod -R 755 events data logs backup storage + ``` + +4. **Deploy using pre-built images** + ```bash + docker compose -f docker-compose.production.yml up -d + ``` + +5. **Check logs** + ```bash + docker compose -f docker-compose.production.yml logs -f + ``` + +### Method 2: Building from Source + 1. **Clone the repository** ```bash git clone https://github.com/the-luap/picpeak.git @@ -64,8 +131,9 @@ This section covers deploying PicPeak using Docker Compose with direct port expo chmod -R 755 events data logs backup storage ``` -4. **Deploy** +4. **Build and deploy** ```bash + docker compose build docker compose up -d ``` @@ -145,12 +213,29 @@ SMTP_PASS=your-sendgrid-api-key ## 📦 Deployment -### Build and Start Services +### Using Pre-built Images (Fastest) ```bash -# Build images +# Pull latest images from GitHub Container Registry +docker pull ghcr.io/the-luap/picpeak/backend:latest +docker pull ghcr.io/the-luap/picpeak/frontend:latest + +# Start services using production compose file +docker compose -f docker-compose.production.yml up -d + +# View running containers +docker compose ps +``` + +### Building from Source (For Customization) + +```bash +# Build images locally docker compose build +# Or build with no cache for clean build +docker compose build --no-cache + # Start all services docker compose up -d @@ -446,14 +531,50 @@ The application includes a built-in backup service. Configure it in the admin pa ### Updates +#### Method 1: Using Pre-built Images (Recommended) + +```bash +# Pull latest changes (for configuration updates) +git pull + +# Pull latest images from GitHub Container Registry +docker compose -f docker-compose.production.yml pull + +# Restart with new images +docker compose -f docker-compose.production.yml down +docker compose -f docker-compose.production.yml up -d + +# Verify services are healthy +docker compose -f docker-compose.production.yml ps +``` + +#### Method 2: Building from Source + ```bash # Pull latest changes git pull # Rebuild and restart docker compose down -docker compose build +docker compose build --no-cache docker compose up -d + +# Verify services are healthy +docker compose ps +``` + +#### Specific Version Updates + +To use a specific version of the images: + +```bash +# Edit docker-compose.production.yml to specify version tags +# Change: ghcr.io/the-luap/picpeak/backend:latest +# To: ghcr.io/the-luap/picpeak/backend:v1.0.0 + +# Then pull and restart +docker compose -f docker-compose.production.yml pull +docker compose -f docker-compose.production.yml up -d ``` ### Database Migrations diff --git a/docker-compose.production.yml b/docker-compose.production.yml new file mode 100644 index 0000000..1d34514 --- /dev/null +++ b/docker-compose.production.yml @@ -0,0 +1,113 @@ +version: '3.8' + +services: + postgres: + image: postgres:15-alpine + container_name: picpeak-postgres + environment: + POSTGRES_USER: ${DB_USER:-picpeak} + POSTGRES_PASSWORD: ${DB_PASSWORD} + POSTGRES_DB: ${DB_NAME:-picpeak} + volumes: + - postgres-data:/var/lib/postgresql/data + networks: + - picpeak-network + restart: unless-stopped + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-picpeak}"] + interval: 10s + timeout: 5s + retries: 5 + + redis: + image: redis:7-alpine + container_name: picpeak-redis + command: redis-server --requirepass ${REDIS_PASSWORD} + volumes: + - redis-data:/data + networks: + - picpeak-network + restart: unless-stopped + healthcheck: + test: ["CMD", "redis-cli", "--raw", "incr", "ping"] + interval: 10s + timeout: 5s + retries: 5 + + backend: + # Use pre-built image from GitHub Container Registry + image: ghcr.io/the-luap/picpeak/backend:latest + container_name: picpeak-backend + env_file: .env + environment: + - NODE_ENV=production + - DB_HOST=postgres + - REDIS_HOST=redis + - PHOTOS_DIR=/app/storage/events + volumes: + - ./storage:/app/storage + - ./logs:/app/logs + - ./data:/app/data + ports: + - "${BACKEND_PORT:-3001}:3000" + networks: + - picpeak-network + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + restart: unless-stopped + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"] + interval: 30s + timeout: 10s + retries: 3 + + frontend: + # Use pre-built image from GitHub Container Registry + image: ghcr.io/the-luap/picpeak/frontend:latest + container_name: picpeak-frontend + environment: + - VITE_API_URL=${FRONTEND_API_URL:-http://localhost:3001} + ports: + - "${FRONTEND_PORT:-3000}:80" + networks: + - picpeak-network + depends_on: + - backend + restart: unless-stopped + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost/health"] + interval: 30s + timeout: 10s + retries: 3 + + # Optional: Nginx reverse proxy for production with SSL + # Uncomment and configure if you want built-in HTTPS support + # nginx: + # image: nginx:alpine + # container_name: picpeak-nginx + # ports: + # - "80:80" + # - "443:443" + # volumes: + # - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro + # - ./nginx/ssl:/etc/nginx/ssl:ro + # - ./nginx/conf.d:/etc/nginx/conf.d:ro + # networks: + # - picpeak-network + # depends_on: + # - frontend + # - backend + # restart: unless-stopped + +volumes: + postgres-data: + driver: local + redis-data: + driver: local + +networks: + picpeak-network: + driver: bridge \ No newline at end of file