hosting-platform/DEPLOYMENT.md

# 🚀 Hosting Platform - Complete Deployment & Architecture Guide

> **Last Updated**: 2026-01-12
> **Purpose**: Complete reference for deployment, architecture, and troubleshooting
> **Use Case**: Read this FIRST when starting any deployment or debugging task

---

## 📊 Server Information

**Server IP**: `176.96.129.77`
**SSH Access**: `ssh -i ~/.ssh/id_rsa root@176.96.129.77`
**OS**: Ubuntu 24.04 LTS
**RAM**: 4GB
**CPU**: 4 cores
**Process Manager**: Supervisor (supervisord)

---

## 🌐 Production URLs

| Service | URL | Port | Status |
|---------|-----|------|--------|
| **Customer Panel** | https://panel.argeict.net | 3001 | ✅ Running |
| **Admin Panel** | https://admin.argeict.net | 5001 | ✅ Running |
| **Backend API** | https://api.argeict.net | 5000 | ✅ Running |
| **Gitea** | https://gitea.argeict.net | 3000 | ✅ Running |

---

## 🎯 Deployed Services

### ✅ Core Services

| Service | Port | Internal URL | Status |
|---------|------|--------------|--------|
| **Frontend (React + Vite)** | 3001 | http://127.0.0.1:3001 | ✅ Running |
| **Backend API (Flask)** | 5000 | http://127.0.0.1:5000 | ✅ Running |
| **Gitea** | 3000 | http://127.0.0.1:3000 | ✅ Running |
| **PostgreSQL** | 5432 | localhost:5432 | ✅ Running |
| **Redis** | 6379 | localhost:6379 | ✅ Running |
| **Nginx (HTTPS)** | 443 | - | ✅ Running |
| **Nginx (HTTP → HTTPS)** | 80 | - | ✅ Running |

### 🔐 Credentials & Access

**Gitea Admin**:
- Username: `hostadmin`
- Password: `HostAdmin2024!`
- Repository: https://gitea.argeict.net/hostadmin/hosting-platform

**PostgreSQL**:
- User: `hosting` (main user)
- Database Names:
  - `hosting` - Customer panel database
  - `admin_hosting_db` - Admin panel database
- Access: `sudo -u postgres psql -d hosting`

**Redis**:
- No password (localhost only)

**SSL Certificates (Let's Encrypt)**:
- Certificate: `/etc/letsencrypt/live/argeict.net/fullchain.pem`
- Private Key: `/etc/letsencrypt/live/argeict.net/privkey.pem`
- Domains: `argeict.net`, `api.argeict.net`, `gitea.argeict.net`, `panel.argeict.net`, `admin.argeict.net`
- Expires: `2026-04-10` (Auto-renewal enabled via certbot timer)

---

## 🏗️ Architecture

```
Internet
    │
    ▼
┌─────────────────────────────────────┐
│   Nginx Reverse Proxy (Port 80)    │
│   - Frontend: /                     │
│   - Backend API: /api               │
│   - Webhook: /webhook               │
└─────────────────────────────────────┘
    │
    ├──────────────┬──────────────┐
    ▼              ▼              ▼
┌─────────┐  ┌──────────┐  ┌──────────┐
│Frontend │  │ Backend  │  │  Gitea   │
│  :3001  │  │  :5000   │  │  :3000   │
└─────────┘  └──────────┘  └──────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
    ┌──────────┐      ┌─────────┐
    │PostgreSQL│      │  Redis  │
    │  :5432   │      │  :6379  │
    └──────────┘      └─────────┘
```

---

## 📁 Directory Structure on Server

### Main Project Locations

```
/opt/hosting-platform/          # 🎯 CUSTOMER PANEL (Main Project)
├── backend/
│   ├── app/
│   │   ├── main.py            # Flask app entry point
│   │   ├── config.py          # Configuration
│   │   ├── models/
│   │   │   ├── domain.py      # Domain model
│   │   │   └── customer.py    # Customer model
│   │   ├── routes/
│   │   │   ├── admin.py       # Admin API routes
│   │   │   └── customer.py    # Customer API routes
│   │   ├── utils/
│   │   │   ├── cloudflare.py  # CF API integration
│   │   │   └── crypto.py      # Encryption utilities
│   │   └── services/
│   ├── venv/                  # Python virtual environment
│   ├── migrations/            # Database migration scripts
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Dashboard.jsx
│   │   │   ├── DomainList.jsx
│   │   │   └── AdminCFAccounts.jsx
│   │   ├── components/
│   │   │   ├── AddDomainWizard.jsx
│   │   │   ├── CFAccountModal.jsx
│   │   │   └── NSInstructions.jsx
│   │   └── services/
│   │       └── api.js         # API client
│   ├── node_modules/
│   ├── package.json
│   └── vite.config.js
└── .git/                      # Git repository

/opt/admin-panel/               # 🎯 ADMIN PANEL (Separate Admin Interface)
├── backend/
│   ├── app/
│   │   └── main.py            # Admin backend entry point
│   └── venv/
└── frontend/

/var/www/panel.argeict.net/     # Nginx static files (if used)
└── html/

/var/www/admin.argeict.net/     # Nginx static files (if used)
└── html/
```

---

## ⚙️ Services & Process Management

### Supervisor Services

Supervisor manages backend and frontend processes. Configuration: `/etc/supervisor/conf.d/`

**Check all services**:
```bash
supervisorctl status
```

**Active Services**:
- `hosting-backend` - Customer panel backend (Python/Flask on port 5000)
- `hosting-frontend` - Customer panel frontend (Vite dev server on port 3001)

**Service Commands**:
```bash
# Restart services
supervisorctl restart hosting-backend
supervisorctl restart hosting-frontend

# Stop/Start
supervisorctl stop hosting-backend
supervisorctl start hosting-backend

# View logs
supervisorctl tail -f hosting-backend
supervisorctl tail -f hosting-frontend

# Or view log files directly
tail -f /var/log/hosting-backend.log
tail -f /var/log/hosting-frontend.log
```

### Running Processes

**Backend Processes**:
```bash
# Customer Backend
Process: /opt/hosting-platform/backend/venv/bin/python /opt/hosting-platform/backend/app/main.py
Port: 5000
Managed by: supervisor (hosting-backend)

# Admin Backend (NOT in supervisor currently)
Process: /opt/admin-panel/backend/venv/bin/python -m app.main
Port: 5001 (or different)
Managed by: Manual process
```

**Frontend Processes**:
```bash
# Vite Dev Server
Process: node /opt/hosting-platform/frontend/node_modules/.bin/vite --host 0.0.0.0 --port 3001
Port: 3001
Managed by: supervisor (hosting-frontend)
```

### Manual Process Management

**Admin Backend** (not in supervisor):
```bash
# Stop admin backend
pkill -f 'admin-panel/backend'

# Start admin backend
cd /opt/admin-panel/backend
source venv/bin/activate
nohup python -m app.main > /var/log/admin-backend.log 2>&1 &
```

**Check all running processes**:
```bash
ps aux | grep -E 'node|python|flask' | grep -v grep
```

---

## 🔄 Deployment Process (STEP-BY-STEP)

### 📝 Pre-Deployment Checklist
- [ ] Code tested locally
- [ ] Database migrations prepared (if needed)
- [ ] Breaking changes documented
- [ ] Backup created (if major changes)

### 1️⃣ Local Development & Commit

```bash
# Navigate to project
cd /Users/oguzozturk/AgumentProje/HostingProjesi/MusteriPanel

# Make your changes...

# Test locally (optional)
cd backend && source venv/bin/activate && python app/main.py
cd frontend && npm run dev

# Commit changes
git add -A
git commit -m "Your descriptive commit message"
git push origin main
```

### 2️⃣ Deploy to Server

```bash
# SSH to server
ssh -i ~/.ssh/id_rsa root@176.96.129.77

# Navigate to project
cd /opt/hosting-platform

# Pull latest changes (RECOMMENDED METHOD)
git fetch origin
git reset --hard origin/main

# Alternative if no conflicts:
git pull origin main
```

### 3️⃣ Run Database Migrations (if needed)

```bash
cd /opt/hosting-platform

# Run migration
sudo -u postgres psql -d hosting -f backend/migrations/YOUR_MIGRATION_FILE.sql

# Verify migration
sudo -u postgres psql -d hosting -c "\d+ TABLE_NAME"
```

### 4️⃣ Restart Services

```bash
# Restart customer backend
supervisorctl restart hosting-backend

# Restart customer frontend (if needed)
supervisorctl restart hosting-frontend

# Restart admin backend (manual)
pkill -f 'admin-panel/backend'
cd /opt/admin-panel/backend
source venv/bin/activate
nohup python -m app.main > /var/log/admin-backend.log 2>&1 &

# Check status
supervisorctl status
ps aux | grep -E 'admin-panel|hosting-platform' | grep python
```

### 5️⃣ Verify Deployment

```bash
# Health check
curl http://localhost:5000/health

# Expected response:
# {"service": "hosting-platform-api", "status": "ok"}

# Check logs for errors
tail -f /var/log/hosting-backend.log
tail -f /var/log/admin-backend.log
```

### 6️⃣ Test in Browser

- Customer Panel: https://panel.argeict.net
- Admin Panel: https://admin.argeict.net
- Test critical features

---

## 🛠️ Management Commands

### Supervisor (Process Management)

```bash
# Check status
supervisorctl status

# Restart services
supervisorctl restart hosting-backend
supervisorctl restart hosting-frontend

# View logs
tail -f /var/log/hosting-backend.log
tail -f /var/log/hosting-frontend.log

# Stop/Start
supervisorctl stop hosting-backend
supervisorctl start hosting-backend
```

### Nginx

```bash
# Test configuration
nginx -t

# Reload
systemctl reload nginx

# Restart
systemctl restart nginx

# View logs
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
```

### Database Management

```bash
# List all databases
sudo -u postgres psql -l

# Connect to hosting database
sudo -u postgres psql -d hosting

# Connect to admin database
sudo -u postgres psql -d admin_hosting_db

# Common queries
sudo -u postgres psql -d hosting -c "SELECT * FROM customers LIMIT 5;"
sudo -u postgres psql -d hosting -c "SELECT * FROM cloudflare_accounts;"
sudo -u postgres psql -d hosting -c "SELECT * FROM domains;"

# Check table structure
sudo -u postgres psql -d hosting -c "\d+ cloudflare_accounts"

# Connect to Redis
redis-cli
```

### Important Database Tables

**hosting database**:
- `customers` - Customer accounts and authentication
- `domains` - Customer domains with CF account assignments
- `cloudflare_accounts` - CF account pool for auto-selection
- `dns_records` - DNS records for domains
- `ssl_certificates` - SSL certificate tracking

**cloudflare_accounts table schema**:
```sql
id                    SERIAL PRIMARY KEY
name                  VARCHAR(255)        -- Account name
email                 VARCHAR(255)        -- CF account email
api_token             TEXT                -- Encrypted API token
max_domains           INTEGER             -- Max domains allowed
current_domain_count  INTEGER             -- Current domain count
is_active             BOOLEAN             -- Active status
use_for_verification  BOOLEAN             -- Use for auto-selection (NEW)
notes                 TEXT                -- Admin notes
created_at            TIMESTAMP
updated_at            TIMESTAMP
```

---

## 🧪 Testing

### Health Check
```bash
curl https://api.argeict.net/health
```

### API Test
```bash
curl https://api.argeict.net/api/domains
```

### Frontend
Open browser: https://argeict.net

### Gitea
Open browser: https://gitea.argeict.net

### SSL Certificate Check
```bash
openssl s_client -connect argeict.net:443 -servername argeict.net < /dev/null 2>/dev/null | openssl x509 -noout -dates
```

---

## 📝 Next Steps

1. ✅ **Add SSL Certificate** (Let's Encrypt)
2. ✅ **Configure Domain Name**
3. ✅ **Set up Monitoring** (Prometheus/Grafana)
4. ✅ **Add Backup System**
5. ✅ **Implement Authentication**

---

## 🆘 Troubleshooting Guide

### ❌ Backend Not Starting

```bash
# 1. Check logs
tail -f /var/log/hosting-backend.log
tail -f /var/log/admin-backend.log

# 2. Check if port is in use
lsof -i :5000
lsof -i :5001

# 3. Check supervisor status
supervisorctl status

# 4. Restart service
supervisorctl restart hosting-backend

# 5. Check for Python errors
cd /opt/hosting-platform/backend
source venv/bin/activate
python app/main.py  # Run manually to see errors
```

### ❌ Frontend Not Loading

```bash
# 1. Check logs
tail -f /var/log/hosting-frontend.log

# 2. Check if Vite is running
ps aux | grep vite

# 3. Check port
lsof -i :3001

# 4. Restart
supervisorctl restart hosting-frontend

# 5. Check Nginx
nginx -t
systemctl status nginx
```

### ❌ Database Connection Issues

```bash
# 1. Check PostgreSQL status
systemctl status postgresql

# 2. Check if database exists
sudo -u postgres psql -l

# 3. Test connection
sudo -u postgres psql -d hosting -c "SELECT 1;"

# 4. Check active connections
sudo -u postgres psql -d hosting -c "SELECT * FROM pg_stat_activity;"

# 5. Restart PostgreSQL (last resort)
systemctl restart postgresql
```

### ❌ Git Pull Conflicts

```bash
# If git pull fails with divergent branches
cd /opt/hosting-platform
git fetch origin
git reset --hard origin/main  # ⚠️ This discards local changes

# Or if you want to keep local changes
git stash
git pull origin main
git stash pop
```

### ❌ Migration Failed

```bash
# 1. Check migration file syntax
cat backend/migrations/YOUR_FILE.sql

# 2. Run migration manually with verbose output
sudo -u postgres psql -d hosting -f backend/migrations/YOUR_FILE.sql -v ON_ERROR_STOP=1

# 3. Check if migration already applied
sudo -u postgres psql -d hosting -c "\d+ TABLE_NAME"

# 4. Rollback if needed (create rollback script first)
sudo -u postgres psql -d hosting -f backend/migrations/rollback_YOUR_FILE.sql
```

### ❌ Supervisor Service Not Found

```bash
# 1. Check supervisor config
ls -la /etc/supervisor/conf.d/

# 2. Reload supervisor config
supervisorctl reread
supervisorctl update

# 3. Restart supervisor
systemctl restart supervisor
```

### ❌ 502 Bad Gateway (Nginx)

```bash
# 1. Check if backend is running
curl http://localhost:5000/health

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

# 3. Check Nginx config
nginx -t

# 4. Restart Nginx
systemctl restart nginx

# 5. Check backend logs
tail -f /var/log/hosting-backend.log
```

---

## 📊 Quick Reference Commands

### Most Common Operations

```bash
# Deploy latest code
ssh -i ~/.ssh/id_rsa root@176.96.129.77
cd /opt/hosting-platform && git fetch origin && git reset --hard origin/main
supervisorctl restart hosting-backend

# Check everything is running
supervisorctl status
ps aux | grep -E 'python.*hosting|python.*admin' | grep -v grep
curl http://localhost:5000/health

# View logs
tail -f /var/log/hosting-backend.log
tail -f /var/log/admin-backend.log

# Database quick check
sudo -u postgres psql -d hosting -c "SELECT COUNT(*) FROM customers;"
sudo -u postgres psql -d hosting -c "SELECT COUNT(*) FROM domains;"
```

---

## 📚 Important Notes

### ⚠️ Before Making Changes
1. **Always read this file first** when starting deployment
2. **Check running processes** before making changes
3. **Backup database** before major migrations
4. **Test locally** before deploying to production

### 🔒 Security Notes
- Never commit `.env` files or credentials
- API tokens are encrypted in database
- SSH key required for server access
- PostgreSQL only accessible from localhost

### 🎯 Best Practices
- Use `git reset --hard origin/main` for clean deployments
- Always check logs after deployment
- Run migrations before restarting services
- Test health endpoint after deployment
- Keep this document updated with changes

---

## 📝 Recent Changes Log

### 2026-01-12
- ✅ Added `use_for_verification` field to `cloudflare_accounts` table
- ✅ Implemented CF account auto-selection logic
- ✅ Added CF token validation and permissions check endpoints
- ✅ Updated admin panel with CF account management UI
- ✅ Updated customer panel with simplified CF selection

### 2026-01-11
- ✅ Fixed company CF account flow
- ✅ Added NS setup step

### 2026-01-10
- ✅ Initial deployment to production server
- ✅ SSL certificates configured
- ✅ Supervisor services configured

---

**Last Updated**: 2026-01-12
**Maintained By**: Hosting Platform Team
**Version**: 2.0.0