# Deploy TagneticAI Email Client on cPanel Shared Hosting

## ⚠️ Important: cPanel Limitations

On cPanel shared hosting, you **cannot**:
- ❌ Install global packages (Node.js, PM2, Nginx)
- ❌ Access root or sudo privileges
- ❌ Install custom system services
- ❌ Modify server configuration files

**But you CAN**:
- ✅ Use cPanel's built-in Node.js support
- ✅ Deploy via cPanel "Setup Node.js App" feature
- ✅ Use addon domains or subdomains
- ✅ Access SSH with limited privileges
- ✅ Manage apps from cPanel interface

---

## Prerequisites

✅ cPanel account with SSH access enabled  
✅ Node.js installed in your cPanel account (or you'll install it)  
✅ Domain: `email.tagneticai.com` (addon domain or subdomain)  
✅ SSL certificate (already in cPanel)  
✅ Mail credentials ready  

---

## 🚀 Deployment Method 1: cPanel Node.js Setup (EASIEST)

### Step 1: Check if Node.js is Available in cPanel

1. **Login to cPanel**
2. Search for **"Setup Node.js App"** or **"Node.js"**
3. If not found, ask your hosting provider to enable it

### Step 2: Create Application Directory

**Via cPanel File Manager**:
1. Go to **File Manager**
2. Create folder: `public_html/email-client` (or your addon domain folder)

**Or via SSH**:
```bash
mkdir -p ~/public_html/email-client
cd ~/public_html/email-client
```

### Step 3: Upload Project Files

**Option A: Using cPanel File Manager**
1. Zip your project locally
2. Upload to `public_html/email-client/`
3. Extract in cPanel

**Option B: Using SFTP**
1. Download WinSCP: https://winscp.net/
2. Connect to your hosting (host, username, password from cPanel)
3. Navigate to `public_html/email-client/`
4. Drag and drop your project files

**Option C: Using SSH**
```bash
# From your local Windows PowerShell:
scp -r "C:\Path\To\TagneticAI-Email Client\app" username@your-cpanel-host:~/public_html/email-client/
scp -r "C:\Path\To\TagneticAI-Email Client\components" username@your-cpanel-host:~/public_html/email-client/
scp "C:\Path\To\TagneticAI-Email Client\package.json" username@your-cpanel-host:~/public_html/email-client/
scp "C:\Path\To\TagneticAI-Email Client\.env.example" username@your-cpanel-host:~/public_html/email-client/
scp "C:\Path\To\TagneticAI-Email Client\next.config.js" username@your-cpanel-host:~/public_html/email-client/
scp "C:\Path\To\TagneticAI-Email Client\tsconfig.json" username@your-cpanel-host:~/public_html/email-client/
scp "C:\Path\To\TagneticAI-Email Client\tailwind.config.ts" username@your-cpanel-host:~/public_html/email-client/
scp "C:\Path\To\TagneticAI-Email Client\postcss.config.js" username@your-cpanel-host:~/public_html/email-client/
```

### Step 4: SSH Into Your cPanel Account

```powershell
ssh username@your-cpanel-host
cd ~/public_html/email-client
```

### Step 5: Create `.env` File

```bash
cp .env.example .env
nano .env
```

Add your mail server details:
```env
EMAIL_HOST=mail.yourdomain.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_PORT=465
EMAIL_USER=your-email@yourdomain.com
EMAIL_PASSWORD=your-email-password
NEXT_PUBLIC_API_URL=https://email.tagneticai.com
NODE_ENV=production
PORT=3000
```

Save: `Ctrl+O` → `Enter` → `Ctrl+X`

### Step 6: Install Dependencies

```bash
npm ci
```

### Step 7: Build Application

```bash
npm run build
```

### Step 8: Setup via cPanel

1. **Go to cPanel** → Search **"Setup Node.js App"**
2. Click **"Create Application"**
3. Fill in:
   - **Node.js version**: 20.x (or latest available)
   - **App mode**: Production
   - **Application root**: `public_html/email-client`
   - **Application start file**: `npm start` or `node_modules/.bin/next start`
   - **Application URL**: `https://email.tagneticai.com`
   - **Port**: 3000

4. Click **"Create"**

cPanel will automatically:
- ✅ Create a systemd service
- ✅ Setup reverse proxy
- ✅ Configure SSL
- ✅ Start your application
- ✅ Auto-restart on crash

### Step 9: Verify

**Check status in cPanel**:
- Go to **Setup Node.js App**
- Your app should show as **"Running"**

**Test in browser**:
```
https://email.tagneticai.com
```

---

## 🔧 Deployment Method 2: Manual SSH Setup (Advanced)

### Step 1-5: Same as Method 1

(Follow steps 1-5 above for uploading and configuring)

### Step 6: Check Available Node.js

```bash
which node
node --version
npm --version
```

If nothing found, contact your hosting provider or use Method 1.

### Step 7-8: Install & Build

```bash
# In ~/public_html/email-client
npm ci
npm run build
```

### Step 9: Create Startup Script

```bash
cat > start.sh << 'EOF'
#!/bin/bash
cd "$(dirname "$0")"
npm start
EOF

chmod +x start.sh
```

### Step 10: Create Systemd Unit (If you have sudo)

```bash
sudo cat > /etc/systemd/system/tagneticai-email.service << 'EOF'
[Unit]
Description=TagneticAI Email Client
After=network.target

[Service]
Type=simple
User=your-cpanel-username
WorkingDirectory=/home/your-username/public_html/email-client
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable tagneticai-email
sudo systemctl start tagneticai-email
```

### Step 11: Configure Reverse Proxy in cPanel

Via cPanel interface:
1. **Addon Domains** → Select `email.tagneticai.com`
2. Look for **"Proxy"** or **"Reverse Proxy"** options
3. Point to: `http://localhost:3000`

Or contact hosting provider for help.

---

## ⚙️ Method 3: Docker on cPanel (If Supported)

Some cPanel providers support Docker. Check:

1. Go to cPanel home
2. Search for **"Docker"** or **"Containers"**
3. If available:
   - Upload `Dockerfile` and `docker-compose.yml`
   - Create container
   - Configure reverse proxy to container port

Contact your hosting provider if unsure.

---

## 🔒 SSL Certificate (Already Configured)

✅ Your SSL certificate is **already in cPanel** (email.tagneticai.com)

The reverse proxy automatically uses it. No extra configuration needed!

---

## 📝 Environment Variables

Your `.env` file on the server should have:

```env
# Mail Server Configuration
EMAIL_HOST=mail.yourdomain.com        # Your mail server hostname
EMAIL_IMAP_PORT=993                    # Usually 993 (TLS) or 143 (no TLS)
EMAIL_SMTP_PORT=465                    # Usually 465 (TLS) or 587 (STARTTLS)
EMAIL_USER=your-email@yourdomain.com   # Your email account
EMAIL_PASSWORD=your-password           # Your email password

# Application Configuration
NODE_ENV=production                    # Keep as production
PORT=3000                              # Internal port (cPanel handles external)
NEXT_PUBLIC_API_URL=https://email.tagneticai.com

# Optional
EMAIL_FROM_NAME=TagneticAI
```

---

## ✅ Verification Checklist

After deployment:

- [ ] App shows as "Running" in cPanel Node.js App setup
- [ ] Browser opens `https://email.tagneticai.com` without errors
- [ ] Email client interface displays (sidebar, email list, reading pane)
- [ ] Emails appear in inbox
- [ ] No SSL certificate warnings
- [ ] Reply/send functionality works

---

## 🆘 Troubleshooting

### "App won't start"

1. Check cPanel logs:
   ```bash
   # Via SSH, in app directory
   tail -f npm-debug.log
   npm start  # Try running manually to see errors
   ```

2. Common issues:
   - Wrong `.env` values → Verify all environment variables
   - Port already in use → Choose different port in cPanel setup
   - Node.js version too old → Request update from hosting provider
   - Missing dependencies → Run `npm ci` again

### "Connection refused to mail server"

1. Test mail server connectivity:
   ```bash
   telnet mail.yourdomain.com 993
   telnet mail.yourdomain.com 465
   ```

2. If fails:
   - Check mail server hostname (should be `mail.`, not `email.`)
   - Verify port numbers (usually 993 for IMAP, 465 for SMTP)
   - Check firewall rules with hosting provider
   - Verify credentials are correct in `.env`

### "502 Bad Gateway"

1. App process might have crashed:
   - Go to cPanel → Setup Node.js App → Restart

2. Port configuration wrong:
   - In cPanel, verify Port is set correctly

### "SSL certificate error"

- Not needed! cPanel handles SSL automatically
- If still seeing errors, clear browser cache and try again

### "Can't access cPanel Terminal"

1. Hosting provider might have disabled SSH
2. Contact hosting provider to enable SSH access
3. Use cPanel Web Terminal instead (if available)

---

## 📞 Key Information to Ask Your Hosting Provider

If deployment doesn't work, ask:

1. **"Is Node.js installed and available via cPanel?"**
2. **"Can I access 'Setup Node.js App' in cPanel?"**
3. **"What version of Node.js is available?"** (Need 18+, preferably 20+)
4. **"Do you provide SSH access for my account?"**
5. **"Can you help me deploy a Node.js/Next.js application?"**
6. **"What port should I use for my application?"** (Usually 3000)

---

## 📊 cPanel Node.js App vs VPS Deployment

| Feature | cPanel | VPS |
|---------|--------|-----|
| Install Node.js | Use cPanel interface | Manual via SSH |
| Process management | cPanel handles | PM2 or systemd |
| Reverse proxy | cPanel handles | Manual Nginx |
| SSL certificate | Auto-configured | Manual setup |
| Restart on crash | Automatic | PM2 handles |
| Monitoring | cPanel interface | Manual logging |
| **Ease** | ✅ Very easy | 🔧 More complex |

---

## 🎯 Next Steps

### Choose Your Method:

**Method 1 (Recommended)**: Use cPanel "Setup Node.js App"
- Easiest
- Built-in monitoring
- Auto-restart
- Best for most users

**Method 2**: Manual SSH setup
- More control
- For advanced users
- Needs hosting provider support

### Then:

1. Upload your project files
2. Create `.env` with mail credentials
3. Follow your chosen method
4. Verify in browser

---

## 📚 Related Documentation

- **WHMCS-DEPLOYMENT.md** - For VPS servers
- **DEPLOYMENT_GUIDE.md** - General deployment guide
- **QUICK_REFERENCE.md** - Command reference
- **README.md** - Application features

---

## 🚀 Ready to Deploy on cPanel?

**Start with Method 1** (cPanel Setup Node.js App). It's the easiest!

If you get stuck:
1. Check the troubleshooting section
2. Contact your hosting provider
3. Ask them to help with Node.js deployment

---

**Your email client will be live on cPanel within 30 minutes!** ✨