create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/plans/12-deployment.md

@@ -0,0 +1,896 @@
+# Deployment Implementation Plan
+
+> **For AI Implementing This Plan:** This is document 12 of 13. Complete documents 01-11 first.
+
+**Goal:** Configure build system for development and production environments, set up deployment scripts, and create CI/CD pipeline configuration.
+
+**Architecture:** Development: Separate plugin servers. Production: Single bundled deployment. Environment variables for configuration. Docker support for containerization.
+
+**Tech Stack:** Modern.js build system, Docker, GitHub Actions CI/CD, environment variable management
+
+---
+
+## Prerequisites
+
+- ✅ Completed all documents 01-11
+- ✅ Application builds and runs locally
+- ✅ All tests pass
+
+---
+
+## Task 1: Create Environment Configuration
+
+**Files:**
+- Create: `.env.example`
+- Create: `.env.development.example`
+- Create: `.env.production.example`
+- Create: `host/.env.example`
+
+### Step 1: Create root environment examples
+
+**File:** `.env.example`
+
+```bash
+# PocketBase Configuration
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+
+# Application Configuration
+VITE_APP_NAME=Lego-One
+VITE_APP_URL=http://localhost:8080
+
+# Feature Flags
+VITE_ENABLE_ANALYTICS=false
+VITE_ENABLE_ERROR_REPORTING=false
+```
+
+**File:** `.env.development.example`
+
+```bash
+# Development Environment
+NODE_ENV=development
+
+# PocketBase (local development)
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+
+# Application URLs
+VITE_APP_URL=http://localhost:8080
+VITE_HOST_PORT=8080
+VITE_DASHBOARD_PORT=3001
+VITE_TODO_PORT=3002
+
+# Feature Flags (development)
+VITE_ENABLE_DEV_TOOLS=true
+VITE_ENABLE_HOT_RELOAD=true
+```
+
+**File:** `.env.production.example`
+
+```bash
+# Production Environment
+NODE_ENV=production
+
+# PocketBase (production - update with actual URL)
+VITE_POCKETBASE_URL=https://your-pocketbase-url.com
+
+# Application URLs
+VITE_APP_URL=https://your-app-url.com
+
+# Feature Flags (production)
+VITE_ENABLE_DEV_TOOLS=false
+VITE_ENABLE_HOT_RELOAD=false
+VITE_ENABLE_ANALYTICS=true
+VITE_ENABLE_ERROR_REPORTING=true
+
+# Analytics (optional)
+VITE_GA_ID=your-google-analytics-id
+VITE_SENTRY_DSN=your-sentry-dsn
+```
+
+### Step 2: Create host environment example
+
+**File:** `host/.env.example`
+
+```bash
+# PocketBase URL (required)
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+
+# App Configuration
+VITE_APP_NAME=Lego-One
+```
+
+---
+
+## Task 2: Create Build Configuration
+
+**Files:**
+- Create: `scripts/build.sh`
+- Create: `scripts/build-all.sh`
+- Modify: `package.json` (root)
+
+### Step 1: Create build script
+
+**File:** `scripts/build.sh`
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🏗️  Building Lego-One..."
+
+# Load environment variables
+if [ -f .env.production ]; then
+  export $(cat .env.production | grep -v '^#' | xargs)
+else
+  echo "⚠️  Warning: .env.production not found"
+fi
+
+# Build host
+echo "📦 Building host..."
+cd host
+pnpm run build
+cd ..
+
+echo "✅ Build complete!"
+echo "📁 Output: host/dist/"
+```
+
+### Step 2: Create build all script
+
+**File:** `scripts/build-all.sh`
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🏗️  Building Lego-One (Production)..."
+
+# Load environment variables
+if [ -f .env.production ]; then
+  export $(cat .env.production | grep -v '^#' | xargs)
+else
+  echo "⚠️  Warning: .env.production not found, using defaults"
+fi
+
+# Check for required environment variables
+if [ -z "$VITE_POCKETBASE_URL" ]; then
+  echo "❌ Error: VITE_POCKETBASE_URL is required"
+  exit 1
+fi
+
+echo "🔧 Configuration:"
+echo "  PocketBase: $VITE_POCKETBASE_URL"
+echo "  App URL: ${VITE_APP_URL:-https://your-app-url.com}"
+
+# Build host (includes bundled plugins)
+echo ""
+echo "📦 Building host application..."
+cd host
+pnpm run build
+
+if [ $? -ne 0 ]; then
+  echo "❌ Build failed"
+  exit 1
+fi
+
+cd ..
+
+echo ""
+echo "✅ Build successful!"
+echo ""
+echo "📁 Output directory: host/dist/"
+echo ""
+echo "🚀 To deploy:"
+echo "   1. Copy host/dist/ to your server"
+echo "   2. Configure your web server to serve static files"
+echo "   3. Set up PocketBase at: $VITE_POCKETBASE_URL"
+echo ""
+echo "📊 Build size:"
+du -sh host/dist
+```
+
+### Step 3: Add build scripts to package.json
+
+**File:** `package.json` (root)
+
+```json
+{
+  "scripts": {
+    "build": "bash scripts/build-all.sh",
+    "build:host": "cd host && pnpm run build",
+    "dev": "pnpm run dev:host",
+    "dev:host": "cd host && pnpm run dev",
+    "dev:all": "concurrently \"pnpm:dev:*\" --kill-others",
+    "lint": "eslint . --ext .ts,.tsx",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "clean": "rm -rf host/dist node_modules/.cache"
+  }
+}
+```
+
+---
+
+## Task 3: Create Development Scripts
+
+**Files:**
+- Create: `scripts/dev.sh`
+- Modify: `package.json` (root)
+
+### Step 1: Create development script
+
+**File:** `scripts/dev.sh`
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🚀 Starting Lego-One development servers..."
+
+# Check if required ports are available
+check_port() {
+  if lsof -Pi :$1 -sTCP:LISTEN -t >/dev/null 2>&1 ; then
+    echo "⚠️  Warning: Port $1 is already in use"
+    read -p "Kill process and continue? (y/n) " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+      lsof -ti:$1 | xargs kill -9
+      echo "✅ Killed process on port $1"
+    else
+      echo "❌ Cannot start server, port $1 is in use"
+      exit 1
+    fi
+  fi
+}
+
+check_port 8080  # Host
+check_port 3001  # Dashboard plugin
+check_port 3002  # Todo plugin
+
+# Start all servers in parallel
+echo ""
+echo "🏠 Starting host on :8080..."
+cd host && pnpm run dev &
+HOST_PID=$!
+cd ..
+
+echo "📊 Starting dashboard plugin on :3001..."
+cd packages/plugins/@lego/plugin-dashboard && pnpm run dev &
+DASHBOARD_PID=$!
+cd ../../..
+
+echo "✓ Starting todo plugin on :3002..."
+cd packages/plugins/@lego/plugin-todo && pnpm run dev &
+TODO_PID=$!
+cd ../../..
+
+echo ""
+echo "✅ All servers started!"
+echo ""
+echo "🌐 Available URLs:"
+echo "  - Host:        http://localhost:8080"
+echo "  - Dashboard:   http://localhost:3001 (standalone)"
+echo "  - Todos:       http://localhost:3002 (standalone)"
+echo ""
+echo "Press Ctrl+C to stop all servers"
+
+# Handle cleanup on exit
+cleanup() {
+  echo ""
+  echo "🛑 Stopping all servers..."
+  kill $HOST_PID $DASHBOARD_PID $TODO_PID 2>/dev/null
+  echo "✅ All servers stopped"
+  exit 0
+}
+
+trap cleanup SIGINT SIGTERM
+
+# Wait for any process to exit
+wait
+```
+
+### Step 2: Add concurrently for dev mode
+
+**File:** `package.json` (root)
+
+Add to devDependencies:
+
+```json
+{
+  "devDependencies": {
+    "concurrently": "^9.0.1"
+  }
+}
+```
+
+---
+
+## Task 4: Create Docker Configuration
+
+**Files:**
+- Create: `Dockerfile`
+- Create: `.dockerignore`
+- Create: `docker-compose.yml`
+- Create: `docker-compose.prod.yml`
+
+### Step 1: Create Dockerfile
+
+**File:** `Dockerfile`
+
+```dockerfile
+# Multi-stage build for production
+
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json pnpm-lock.yaml ./
+COPY packages/host/package.json ./packages/host/
+COPY packages/plugins/@lego/plugin-dashboard/package.json ./packages/plugins/@lego/plugin-dashboard/
+COPY packages/plugins/@lego/plugin-todo/package.json ./packages/plugins/@lego/plugin-todo/
+
+RUN npm install -g pnpm@9
+RUN pnpm install --frozen-lockfile
+
+# Copy source and build
+COPY . .
+
+# Build for production
+ARG NODE_ENV=production
+ENV NODE_ENV=$NODE_ENV
+RUN pnpm run build
+
+# Production stage
+FROM nginx:alpine AS production
+
+# Copy built files from build stage
+COPY --from=builder /app/host/dist /usr/share/nginx/html
+
+# Copy nginx configuration
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+
+# Expose port
+EXPOSE 80
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost/ || exit 1
+
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+### Step 2: Create nginx config
+
+**File:** `docker/nginx.conf`
+
+```nginx
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Enable gzip compression
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+
+    # SPA routing - redirect all routes to index.html
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Disable caching for HTML files
+    location ~* \.html$ {
+        add_header Cache-Control "no-cache, no-store, must-revalidate";
+    }
+}
+```
+
+### Step 3: Create dockerignore
+
+**File:** `.dockerignore`
+
+```
+node_modules
+npm-debug.log
+.git
+.gitignore
+.env
+.env.*
+.vscode
+.idea
+*.md
+docs
+scripts
+coverage
+dist
+.modern
+.DS_Store
+Thumbs.db
+```
+
+### Step 4: Create docker-compose for development
+
+**File:** `docker-compose.yml`
+
+```yaml
+version: '3.8'
+
+services:
+  pocketbase:
+    image: ghcr.io/muchb8/pocketbase:latest
+    container_name: lego-one-pb
+    ports:
+      - "8090:8090"
+    volumes:
+      - ./pocketbase/pb_data:/pb_data
+    environment:
+      - POCKETBASE_ENCRYPTION_ENV=automatic
+    restart: unless-stopped
+
+  # Development: Run host and plugins separately
+  host:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    container_name: lego-one-host
+    ports:
+      - "8080:8080"
+    environment:
+      - VITE_POCKETBASE_URL=http://pocketbase:8090
+    depends_on:
+      - pocketbase
+    volumes:
+      - ./host:/app/host
+      - ./packages:/app/packages
+      - /app/node_modules
+    command: pnpm run dev:host
+    restart: unless-stopped
+
+volumes:
+  pb_data:
+```
+
+### Step 5: Create docker-compose for production
+
+**File:** `docker-compose.prod.yml`
+
+```yaml
+version: '3.8'
+
+services:
+  pocketbase:
+    image: ghcr.io/muchb8/pocketbase:latest
+    container_name: lego-one-pb
+    ports:
+      - "8090:8090"
+    volumes:
+      - ./pocketbase/pb_data:/pb_data
+    environment:
+      - POCKETBASE_ENCRYPTION_ENV=${POCKETBASE_ENCRYPTION_ENV}
+    restart: unless-stopped
+    networks:
+      - lego-network
+
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        NODE_ENV: production
+    container_name: lego-one-app
+    ports:
+      - "80:80"
+    environment:
+      - VITE_POCKETBASE_URL=${POCKETBASE_URL}
+    depends_on:
+      - pocketbase
+    restart: unless-stopped
+    networks:
+      - lego-network
+
+volumes:
+  pb_data:
+
+networks:
+  lego-network:
+    driver: bridge
+```
+
+---
+
+## Task 5: Create CI/CD Pipeline
+
+**Files:**
+- Create: `.github/workflows/ci.yml`
+- Create: `.github/workflows/deploy.yml`
+
+### Step 1: Create CI workflow
+
+**File:** `.github/workflows/ci.yml`
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run ESLint
+        run: pnpm run lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run unit tests
+        run: pnpm run test:run
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/coverage-final.json
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build application
+        run: pnpm run build
+        env:
+          VITE_POCKETBASE_URL: http://localhost:8090
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: dist
+          path: host/dist/
+```
+
+### Step 2: Create deployment workflow
+
+**File:** `.github/workflows/deploy.yml`
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Deploy to Production
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build application
+        run: pnpm run build
+        env:
+          VITE_POCKETBASE_URL: ${{ secrets.POCKETBASE_URL }}
+
+      - name: Deploy to server
+        uses: easingthemes/ssh-deploy@main
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
+          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
+          REMOTE_USER: ${{ secrets.REMOTE_USER }}
+          TARGET: /var/www/lego-one
+        with:
+          SOURCE: "host/dist/*"
+          ARGS: "-rlgoDzvc -i --delete"
+
+      - name: Restart services
+        uses: appleboy/ssh-action@master
+        with:
+          host: ${{ secrets.REMOTE_HOST }}
+          username: ${{ secrets.REMOTE_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            cd /var/www/lego-one
+            docker-compose -f docker-compose.prod.yml pull
+            docker-compose -f docker-compose.prod.yml up -d --build
+            docker system prune -f
+```
+
+---
+
+## Task 6: Create Production Deployment Guide
+
+**Files:**
+- Create: `docs/deployment.md`
+
+### Step 1: Create deployment documentation
+
+**File:** `docs/deployment.md`
+
+```markdown
+# Deployment Guide
+
+## Prerequisites
+
+- Server with Docker and Docker Compose installed
+- Domain name configured
+- SSL certificate (recommended)
+
+## Environment Variables
+
+Create `.env.production`:
+
+```bash
+POCKETBASE_URL=https://your-pocketbase-url.com
+POCKETBASE_ENCRYPTION_ENV=your-encryption-key
+```
+
+## Deployment Steps
+
+### Option 1: Docker Compose (Recommended)
+
+1. Copy files to server:
+```bash
+rsync -avz --exclude 'node_modules' --exclude '.git' \
+  ./ user@server:/var/www/lego-one/
+```
+
+2. SSH into server and deploy:
+```bash
+cd /var/www/lego-one
+docker-compose -f docker-compose.prod.yml up -d --build
+```
+
+3. Configure reverse proxy (Nginx):
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:80;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+### Option 2: Manual Deployment
+
+1. Build locally:
+```bash
+pnpm run build
+```
+
+2. Upload `host/dist/` to server
+
+3. Configure web server to serve static files
+
+## PocketBase Setup
+
+1. Download PocketBase binary
+2. Run migrations: `./pocketbase serve --migrationDir=pocketbase/migrations`
+3. Configure reverse proxy for port 8090
+
+## Monitoring
+
+- Check logs: `docker-compose logs -f`
+- Health check: `curl http://localhost/`
+```
+
+---
+
+## Task 7: Create Deployment Scripts
+
+**Files:**
+- Create: `scripts/deploy.sh`
+
+### Step 1: Create deployment script
+
+**File:** `scripts/deploy.sh`
+
+```bash
+#!/bin/bash
+set -e
+
+# Configuration
+SERVER_USER="${DEPLOY_USER:-root}"
+SERVER_HOST="${DEPLOY_HOST:-localhost}"
+SERVER_PATH="${DEPLOY_PATH:-/var/www/lego-one}"
+
+echo "🚀 Deploying to $SERVER_USER@$SERVER_HOST:$SERVER_PATH"
+
+# Build application
+echo "📦 Building application..."
+pnpm run build
+
+# Deploy via rsync
+echo "📤 Uploading files..."
+rsync -avz --delete \
+  --exclude 'node_modules' \
+  --exclude '.git' \
+  --exclude 'coverage' \
+  --exclude '.env.*' \
+  host/dist/ \
+  $SERVER_USER@$SERVER_HOST:$SERVER_PATH/dist/
+
+# Restart services
+echo "🔄 Restarting services..."
+ssh $SERVER_USER@$SERVER_HOST << 'ENDSSH'
+  cd $SERVER_PATH
+  docker-compose -f docker-compose.prod.yml pull
+  docker-compose -f docker-compose.prod.yml up -d --build
+  docker system prune -f
+ENDSSH
+
+echo "✅ Deployment complete!"
+echo "🌐 https://$SERVER_HOST"
+```
+
+---
+
+## Verification
+
+### Step 1: Test production build
+
+**Run:**
+
+```bash
+cp .env.production.example .env.production
+# Edit .env.production with actual values
+pnpm run build
+```
+
+Expected: Build completes successfully, `host/dist/` contains all files.
+
+### Step 2: Test Docker build
+
+**Run:**
+
+```bash
+docker build -t lego-one:test .
+```
+
+Expected: Docker image builds successfully.
+
+### Step 3: Test Docker Compose
+
+**Run:**
+
+```bash
+docker-compose -f docker-compose.prod.yml config
+```
+
+Expected: Configuration is valid.
+
+---
+
+## Summary
+
+After completing this document, you will have:
+
+1. ✅ Environment configuration for dev and production
+2. ✅ Build scripts for single-command builds
+3. ✅ Development script for running all servers
+4. ✅ Docker configuration for containerization
+5. ✅ Docker Compose for local development and production
+6. ✅ CI/CD pipeline with GitHub Actions
+7. ✅ Deployment scripts and documentation
+8. ✅ Production-ready deployment strategy
+
+**Next:** `13-setup-guide.md` - Create user guide for setup, plugin development, and configuration.
+
+---
+
+## Files Created
+
+```
+root/
+├── .env.example
+├── .env.development.example
+├── .env.production.example
+├── Dockerfile
+├── .dockerignore
+├── docker-compose.yml
+├── docker-compose.prod.yml
+├── docker/
+│   └── nginx.conf
+├── scripts/
+│   ├── build.sh
+│   ├── build-all.sh
+│   ├── dev.sh
+│   └── deploy.sh
+└── .github/
+    └── workflows/
+        ├── ci.yml
+        └── deploy.yml
+
+host/
+└── .env.example
+
+docs/
+└── deployment.md
+```