ankhbayar/Assist_Design
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Assist_Design/docs/QUICK_START.md
T. Narantuya 80580da46d Initial Customer Portal setup - production ready
2025-08-20 18:02:50 +09:00

7.0 KiB
Raw Blame History

🚀 Quick Start: Deploy to Plesk in 15 Minutes

This guide will get your Customer Portal deployed to Plesk using native Git integration - simple, reliable, and maintenance-free!

🎯 Why This Approach?

  • ✅ No complex scripts - Plesk handles everything
  • ✅ Auto-deployment - Push to GitHub → Instant deployment
  • ✅ Built-in backups - Easy rollback if needed
  • ✅ Plesk managed - UI-based configuration
  • ✅ 15 minutes setup - Much faster than custom pipelines

📋 Prerequisites

Before you start, ensure you have:

  • ✅ Plesk hosting account with Git support
  • ✅ Domain configured in Plesk
  • ✅ GitHub repository (can be private)
  • ✅ Local development environment set up

🛠️ Step 1: Prepare Your Repository (2 minutes)

1.1 Set Up Local Environment

# Copy environment templates and configure with your values
cp apps/bff/.env.example apps/bff/.env
cp apps/portal/.env.example apps/portal/.env.local

# Edit with your actual credentials (these files are git-ignored)
nano apps/bff/.env
nano apps/portal/.env.local

1.2 Test Your Build Locally

# Install dependencies
pnpm install

# Test build process
pnpm build

# Verify everything works
pnpm dev

1.3 Push to GitHub

git init
git add .
git commit -m "Initial Customer Portal setup"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

🌐 Step 2: Configure Plesk Git Integration (8 minutes)

2.1 Access Plesk Git

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

2.2 Add Your Repository

  1. Click Add Repository
  2. Choose Remote Git hosting
  3. Fill in details:
Repository URL: https://github.com/yourusername/your-repo.git
Repository name: customer-portal
Branch: main
Deployment mode: ☑️ Automatic deployment

2.3 Configure Paths

Repository path: /var/www/vhosts/yourdomain.com/git/customer-portal
Document root: /var/www/vhosts/yourdomain.com/httpdocs
Actions: ☑️ Pull updates automatically

2.4 Set Up Authentication (If Private Repo)

  1. Plesk will generate an SSH public key
  2. Copy this key
  3. Go to GitHub: Repo → Settings → Deploy keys
  4. Click Add deploy key
  5. Paste the key, give it a name: "Plesk Deploy Key"
  6. ✅ Allow write access (if you want Plesk to push back)
  7. Save

🔗 Step 3: Configure GitHub Webhook (3 minutes)

3.1 Get Webhook URL from Plesk

  1. In Plesk Git settings, find the webhook URL
  2. Copy it (looks like: https://yourserver.com:8443/git/webhook/...)

3.2 Add Webhook to GitHub

  1. GitHub repo → Settings → Webhooks
  2. Click Add webhook
  3. Configure:
Payload URL: [Paste Plesk webhook URL]
Content type: application/json
Secret: [Leave empty]
Events: ☑️ Just the push event
Active: ☑️ Enabled
  1. Add webhook

🔧 Step 4: Configure Build Process (2 minutes)

Option A: Simple File Copy (Recommended for Start)

In Plesk Git settings, add Additional deployment actions:

# Copy built files to web root
cp -r apps/portal/out/* /var/www/vhosts/yourdomain.com/httpdocs/ 2>/dev/null || true
cp -r apps/portal/public/* /var/www/vhosts/yourdomain.com/httpdocs/ 2>/dev/null || true

# Set proper permissions
chmod -R 755 /var/www/vhosts/yourdomain.com/httpdocs/

Option B: Full Build Process (If You Need Server-Side Building)

# Navigate to repository
cd /var/www/vhosts/yourdomain.com/git/customer-portal

# Install PNPM if not available
curl -fsSL https://get.pnpm.io/install.sh | sh -
export PATH="$HOME/.local/share/pnpm:$PATH"

# Install dependencies and build
pnpm install --frozen-lockfile
pnpm build

# Deploy built files
cp -r apps/portal/dist/* /var/www/vhosts/yourdomain.com/httpdocs/
mkdir -p /var/www/vhosts/yourdomain.com/httpdocs/api
cp -r apps/bff/dist/* /var/www/vhosts/yourdomain.com/httpdocs/api/

# Set permissions
chmod -R 755 /var/www/vhosts/yourdomain.com/httpdocs/

🚀 Step 5: First Deployment Test

5.1 Trigger Deployment

Make a small change and push:

echo "# Customer Portal" > README.md
git add README.md
git commit -m "Test deployment"
git push origin main

5.2 Monitor Deployment

  1. GitHub: Check webhook delivery in repo settings
  2. Plesk: Watch Git logs for deployment progress
  3. Website: Visit your domain to see if it's live!

🎯 Step 6: Production Configuration

6.1 Environment Variables

In Plesk, set up your production environment:

  1. Websites & Domains → PHP Settings
  2. Add environment variables:
NEXT_PUBLIC_API_BASE=https://yourdomain.com/api
NODE_ENV=production
DATABASE_URL=your_production_db_url
REDIS_URL=your_production_redis_url

6.2 SSL Certificate

  1. Websites & Domains → SSL/TLS Certificates
  2. Get free certificate (Let's Encrypt)
  3. Install and Secure the domain

✅ Verification Checklist

After setup, verify everything works:

  • Website loads: Visit https://yourdomain.com
  • API responds: Test https://yourdomain.com/api/health
  • Auto-deployment: Push a change and see it deploy
  • Webhook active: Check GitHub webhook shows recent deliveries
  • SSL enabled: Site shows green lock in browser

🔄 Daily Workflow

Your new deployment process is now:

  1. Develop locally: Make changes, test with pnpm dev
  2. Commit & push: git add . && git commit -m "Your change" && git push
  3. Auto-deploy: Plesk automatically deploys within 1-2 minutes
  4. Verify: Check your live site

That's it! No complex pipelines, no maintenance, no headaches! 🎉

🆘 Troubleshooting

Deployment Not Working?

  1. Check webhook: GitHub repo → Settings → Webhooks → Recent deliveries
  2. Check Plesk logs: Git → Repository → View logs
  3. Test manually: Plesk → Git → Pull Updates button

Build Failing?

  1. Check build locally: Run pnpm build on your machine
  2. Check server logs: Plesk → Git → Deployment logs
  3. Simplify build: Start with Option A (file copy only)

Site Not Loading?

  1. Check file permissions: Should be 755 for directories, 644 for files
  2. Check document root: Files should be in /httpdocs/
  3. Check DNS: Domain should point to your Plesk server

📚 What's Next?

  • Database setup: Configure PostgreSQL in Plesk
  • Email setup: Configure SMTP for notifications
  • Monitoring: Set up Plesk monitoring alerts
  • Backups: Configure automatic backups
  • CDN setup: Configure Cloudflare for better performance

🎊 Congratulations!

You now have a professional, automated deployment pipeline that:

  • ✅ Deploys automatically on every push
  • ✅ Requires zero maintenance
  • ✅ Has built-in rollback capability
  • ✅ Is managed through Plesk's intuitive UI
  • ✅ Scales with your team

Much simpler than complex GitHub Actions, right? 😊

Need help? Check out PLESK_DEPLOYMENT.md for detailed technical information.