Assist_Design/docs/PLESK_DEPLOYMENT.md

🚀 Plesk Native Git Deployment Guide

This guide shows how to deploy your Customer Portal using Plesk's built-in Git integration - much simpler than custom scripts!

🎯 Why Plesk Native Integration?

• ✅ No complex scripts - Plesk handles everything
• ✅ Automatic deployment - Deploy on every git push
• ✅ Built-in backups - Plesk creates rollback points
• ✅ Easy management - Configure via Plesk UI
• ✅ Webhook support - GitHub triggers deployment automatically

📋 Prerequisites

• Plesk hosting account with Git support
• GitHub repository (this one!)
• Domain/subdomain configured in Plesk

🛠️ Setup Steps

1. Enable Git in Plesk

1. Log into your Plesk control panel
2. Navigate to Websites & Domains
3. Select your domain
4. Click Git (in the left sidebar)

2. Add Your Repository

1. Click Add Repository
2. Choose Remote Git hosting
3. Enter repository details:

   Repository URL: https://github.com/yourusername/new-portal-website.git
   Repository name: customer-portal
   Branch: main
   

3. Configure Deployment

1. Deployment mode: Select Automatic deployment
2. Repository path: /var/www/vhosts/yourdomain.com/git/customer-portal
3. Document root: /var/www/vhosts/yourdomain.com/httpdocs
4. Actions: Enable Pull updates automatically

4. Set Up Authentication (For Private Repos)

If your repository is private:

1. Plesk will generate an SSH public key
2. Copy this key
3. Go to your GitHub repo → Settings → Deploy keys
4. Click Add deploy key
5. Paste the Plesk SSH key
6. ✅ Check Allow write access (if needed)
7. Click Add key

5. Configure GitHub Webhook

1. In Plesk Git settings, copy the webhook URL
2. Go to GitHub repo → Settings → Webhooks
3. Click Add webhook
4. Paste the Plesk webhook URL
5. Set Content type: application/json
6. Select Just the push event
7. ✅ Check Active
8. Click Add webhook

🔧 Build Configuration (Optional)

If you need to run build commands (like pnpm build), you can:

Option A: Plesk Build Commands

In Plesk Git settings, add deployment actions:

# Navigate to the project root
cd /var/www/vhosts/yourdomain.com/git/customer-portal

# Install dependencies
curl -fsSL https://get.pnpm.io/install.sh | sh -
export PATH="$HOME/.local/share/pnpm:$PATH"
pnpm install --frozen-lockfile

# Build the project
pnpm build

# Copy built files to document root
cp -r apps/portal/dist/* /var/www/vhosts/yourdomain.com/httpdocs/
cp -r apps/bff/dist/* /var/www/vhosts/yourdomain.com/httpdocs/api/

Option B: Keep Simple GitHub Action

Keep a minimal build workflow (optional):

# .github/workflows/build.yml
name: Build Assets
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v2
      with:
        version: 8
    - name: Build
      run: |
        pnpm install
        pnpm build
    - name: Commit built assets
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add apps/portal/dist apps/bff/dist
        git commit -m "Build assets" || exit 0
        git push

🎯 Deployment Process

Once configured, deployment is automatic:

1. Developer pushes to main branch
2. GitHub webhook notifies Plesk
3. Plesk pulls latest changes
4. Plesk runs build commands (if configured)
5. Plesk deploys to document root
6. Site is live! 🚀

🔍 Monitoring & Management

Check Deployment Status

• Plesk → Git → View deployment logs
• Check webhook delivery in GitHub repo settings

Manual Deployment

• Plesk → Git → Pull Updates button

Rollback

• Plesk → Git → Repository History
• Select previous commit → Deploy

🚨 Troubleshooting

Webhook Not Working

• Check webhook URL in GitHub matches Plesk
• Verify webhook is active and recent deliveries show success
• Check Plesk Git logs for errors

Build Failures

• Check Plesk deployment logs
• Verify all dependencies are available on server
• Test build commands manually via SSH

Permission Issues

• Ensure Plesk has write access to document root
• Check file permissions after deployment

🎉 Benefits You'll Get

• Zero maintenance deployment pipeline
• Instant deployments on every push
• Built-in rollback capability
• No complex GitHub Actions to maintain
• Plesk-managed file permissions and ownership

📝 Next Steps

1. Follow the setup steps above
2. Test with a small change (edit README.md)
3. Push to main branch
4. Watch it deploy automatically! 🎯

Much simpler than custom deployment scripts, right? 😊