Assist_Design/docs/QUICK_START.md

# 🚀 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

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

```bash
# Install dependencies
pnpm install

# Test build process
pnpm build

# Verify everything works
pnpm dev
```

### 1.3 Push to GitHub

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

4. **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**:

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

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

```bash
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](./PLESK_DEPLOYMENT.md) for detailed technical information.