# 📦 LuckyChit Deployment Files

This directory contains everything you need to deploy your LuckyChit application on Proxmox LXC.

## 📚 Documentation Files

### 1. **PROXMOX_DEPLOYMENT_GUIDE.md** ⭐ Main Guide
   - **Comprehensive step-by-step deployment guide**
   - Covers everything from LXC creation to production deployment
   - Includes troubleshooting, security checklist, and maintenance
   - **Time Required:** 30-45 minutes
   - **Recommended for:** First-time deployments

### 2. **QUICK_DEPLOY.md** ⚡ Quick Reference
   - **Quick command reference for experienced users**
   - One-liner commands for common operations
   - Useful paths and troubleshooting commands
   - **Time Required:** 20-30 minutes
   - **Recommended for:** Quick deployments or reference

### 3. **deploy.sh** 🤖 Automated Script
   - **Automated deployment script**
   - Installs all prerequisites automatically
   - Sets up database, users, and configuration
   - **Time Required:** 10-15 minutes + manual code deployment
   - **Recommended for:** Fastest deployment

---

## 🚀 Which Method Should You Use?

### Option 1: Automated Script (Fastest) ⚡

**Best for:** Quick setup, first-time Linux users

```bash
# 1. Create Ubuntu 22.04 LXC on Proxmox
# 2. Enter the container
pct enter <container-id>

# 3. Download and run the script
curl -o deploy.sh https://raw.githubusercontent.com/YOUR_REPO/deploy.sh
chmod +x deploy.sh
sudo ./deploy.sh

# 4. Upload your code and deploy
# Follow the on-screen instructions
```

**Pros:**
- ✅ Fastest method
- ✅ Less room for error
- ✅ Automatically configures everything

**Cons:**
- ❌ Less learning opportunity
- ❌ Requires internet connection

---

### Option 2: Manual Deployment (Learning & Control) 📖

**Best for:** Understanding the system, custom configurations

```bash
# Follow PROXMOX_DEPLOYMENT_GUIDE.md step-by-step
```

**Pros:**
- ✅ Full control over every step
- ✅ Better understanding of the system
- ✅ Easy to customize
- ✅ Learn server administration

**Cons:**
- ❌ Takes longer
- ❌ More typing

---

### Option 3: Quick Commands (Experienced Users) ⚡

**Best for:** Experienced admins, subsequent deployments

```bash
# Use QUICK_DEPLOY.md for rapid deployment
# Copy-paste command blocks
```

**Pros:**
- ✅ Fast for experienced users
- ✅ Good for reference
- ✅ Flexible

**Cons:**
- ❌ Requires Linux experience
- ❌ Easy to miss steps if not careful

---

## 🗂️ Project Structure After Deployment

```
/home/luckychit/
├── apps/
│   └── chitfund/
│       ├── backend/              # Node.js backend
│       │   ├── src/
│       │   ├── .env              # Environment variables (KEEP SECURE!)
│       │   └── package.json
│       └── luckychit/            # Flutter frontend
│           ├── lib/
│           ├── build/web/        # Built web files
│           └── pubspec.yaml
├── logs/                         # Application logs
├── backups/                      # Database backups
└── backup-db.sh                  # Backup script

/var/www/luckychit/               # Nginx web root (Flutter web)
/etc/nginx/sites-available/       # Nginx configuration
/var/log/nginx/                   # Nginx logs
```

---

## 📋 Deployment Checklist

### Pre-Deployment
- [ ] Proxmox LXC container created (Ubuntu 22.04)
- [ ] Container has network access
- [ ] You have root/sudo access
- [ ] You have your code ready (Git repo or files to upload)

### During Deployment
- [ ] System updated
- [ ] Node.js installed (v20)
- [ ] PostgreSQL installed and configured
- [ ] Nginx installed
- [ ] PM2 installed
- [ ] Flutter installed (for web build)
- [ ] Firewall configured
- [ ] Database created with secure password
- [ ] Backend code deployed
- [ ] Frontend built and deployed
- [ ] PM2 configured to auto-start
- [ ] Nginx configured correctly

### Post-Deployment
- [ ] Test health endpoint: `curl http://localhost:3000/health`
- [ ] Test frontend: Visit `http://YOUR_IP`
- [ ] Test API: Try login from frontend
- [ ] Check logs: `pm2 logs`
- [ ] Setup SSL certificate (Let's Encrypt)
- [ ] Configure automated backups
- [ ] Document your credentials (securely!)
- [ ] Test from external network

---

## 🔐 Important Security Notes

### Immediately After Deployment:

1. **Change Default Passwords**
   ```bash
   # PostgreSQL password
   sudo -u postgres psql
   ALTER USER luckychit WITH PASSWORD 'new_secure_password';
   
   # Update .env file accordingly
   nano /home/luckychit/apps/chitfund/backend/.env
   ```

2. **Secure JWT Secret**
   - Generate a strong random secret (32+ characters)
   - Never commit .env to Git
   - Use different secrets for dev/staging/production

3. **Setup SSL/HTTPS**
   ```bash
   sudo apt install certbot python3-certbot-nginx
   sudo certbot --nginx -d yourdomain.com
   ```

4. **Enable Fail2Ban** (Optional but recommended)
   ```bash
   sudo apt install fail2ban
   sudo systemctl enable fail2ban
   sudo systemctl start fail2ban
   ```

5. **Regular Updates**
   ```bash
   # Create update script
   echo '#!/bin/bash' > ~/update-system.sh
   echo 'apt update && apt upgrade -y' >> ~/update-system.sh
   chmod +x ~/update-system.sh
   
   # Run weekly via crontab
   # 0 3 * * 0 /root/update-system.sh
   ```

---

## 🛠️ Common Post-Deployment Tasks

### Update Application Code

```bash
# Backend
cd /home/luckychit/apps/chitfund/backend
git pull
npm install --production
pm2 reload luckychit-api

# Frontend
cd /home/luckychit/apps/chitfund/luckychit
git pull
flutter pub get
flutter build web --release
sudo cp -r build/web/* /var/www/luckychit/
```

### View Logs

```bash
# PM2 logs (backend)
pm2 logs luckychit-api

# Nginx access logs
sudo tail -f /var/log/nginx/access.log

# Nginx error logs
sudo tail -f /var/log/nginx/error.log

# PostgreSQL logs
sudo tail -f /var/log/postgresql/postgresql-14-main.log
```

### Database Backup & Restore

```bash
# Manual backup
pg_dump -U luckychit -h localhost luckychit > backup.sql

# Restore
psql -U luckychit -h localhost luckychit < backup.sql

# Automated backups are already setup (runs daily at 2 AM)
# Check /home/luckychit/backups/
```

### Monitor Resources

```bash
# System resources
htop

# PM2 monitoring
pm2 monit

# Disk space
df -h

# Memory
free -h

# Network connections
sudo netstat -tulpn
```

---

## 🆘 Troubleshooting Quick Guide

### Backend Won't Start
```bash
pm2 logs luckychit-api              # Check logs
node /home/luckychit/apps/chitfund/backend/test-db-connection.js  # Test DB
cat /home/luckychit/apps/chitfund/backend/.env  # Verify config
```

### Can't Access from Browser
```bash
sudo ufw status                     # Check firewall
sudo systemctl status nginx         # Check Nginx
sudo nginx -t                       # Test Nginx config
curl http://localhost:3000/health   # Test backend locally
```

### Database Connection Issues
```bash
sudo systemctl status postgresql    # Check PostgreSQL
sudo -u postgres psql               # Try connecting
# Inside psql: \l                   # List databases
# Inside psql: \du                  # List users
```

### Out of Disk Space
```bash
df -h                               # Check space
du -sh /home/luckychit/* | sort -h  # Find large directories
pm2 flush                           # Clear PM2 logs
sudo journalctl --vacuum-time=3d    # Clear system logs
```

---

## 📞 Support Resources

- **Full Guide:** `PROXMOX_DEPLOYMENT_GUIDE.md`
- **Quick Commands:** `QUICK_DEPLOY.md`
- **Automated Script:** `deploy.sh`

### External Resources
- [Proxmox Documentation](https://pve.proxmox.com/wiki/Main_Page)
- [Node.js Documentation](https://nodejs.org/en/docs/)
- [Flutter Documentation](https://docs.flutter.dev/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Nginx Documentation](https://nginx.org/en/docs/)
- [PM2 Documentation](https://pm2.keymetrics.io/)

---

## 🎯 Success Criteria

Your deployment is successful when:

- ✅ Frontend loads in browser: `http://YOUR_IP`
- ✅ Health endpoint responds: `http://YOUR_IP/health`
- ✅ Can login and use the application
- ✅ PM2 shows app running: `pm2 status`
- ✅ Nginx is running: `sudo systemctl status nginx`
- ✅ Database is accessible: `psql -U luckychit -d luckychit -h localhost`
- ✅ Application survives reboot (test with `sudo reboot`)
- ✅ Firewall is enabled: `sudo ufw status`
- ✅ Automated backups are scheduled: `crontab -l`

---

## 📈 Next Steps After Deployment

1. **Setup Monitoring**
   - Install monitoring tools (Netdata, Prometheus, etc.)
   - Setup uptime monitoring (UptimeRobot, etc.)
   - Configure email alerts

2. **Performance Optimization**
   - Enable Nginx caching
   - Configure database connection pooling
   - Setup CDN for static assets

3. **Backup Strategy**
   - Test backup restoration
   - Setup off-site backups
   - Document recovery procedures

4. **Documentation**
   - Document your specific configuration
   - Keep credentials in password manager
   - Create runbook for common issues

5. **Team Access**
   - Create additional user accounts if needed
   - Setup SSH key authentication
   - Configure proper permissions

---

## 🎉 You're All Set!

Your LuckyChit application should now be running smoothly on Proxmox LXC.

**Remember:**
- Keep your system updated
- Monitor logs regularly
- Test backups periodically
- Use HTTPS in production
- Document any custom changes

Good luck! 🚀