Update DEPLOYMENT.md with complete architecture and process documentation
This commit is contained in:
oguz ozturk
parent
84c8cb728e
commit
9a2f47ee57
507
DEPLOYMENT.md
507
DEPLOYMENT.md
|
|
@ -1,21 +1,30 @@
|
|||
# 🚀 Deployment Guide - Hosting Platform
|
||||
# 🚀 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 | Status |
|
||||
|---------|-----|--------|
|
||||
| **Frontend** | https://argeict.net | ✅ Running |
|
||||
| **Backend API** | https://api.argeict.net | ✅ Running |
|
||||
| **Gitea** | https://gitea.argeict.net | ✅ Running |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -33,7 +42,7 @@
|
|||
| **Nginx (HTTPS)** | 443 | - | ✅ Running |
|
||||
| **Nginx (HTTP → HTTPS)** | 80 | - | ✅ Running |
|
||||
|
||||
### 🔐 Credentials
|
||||
### 🔐 Credentials & Access
|
||||
|
||||
**Gitea Admin**:
|
||||
- Username: `hostadmin`
|
||||
|
|
@ -41,9 +50,11 @@
|
|||
- Repository: https://gitea.argeict.net/hostadmin/hosting-platform
|
||||
|
||||
**PostgreSQL**:
|
||||
- User: `hosting_user`
|
||||
- Password: `HostingDB2024!`
|
||||
- Database: `hosting_db`
|
||||
- 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)
|
||||
|
|
@ -51,7 +62,7 @@
|
|||
**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`
|
||||
- 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)
|
||||
|
||||
---
|
||||
|
|
@ -86,49 +97,233 @@ Internet
|
|||
|
||||
---
|
||||
|
||||
## 📁 Directory Structure
|
||||
## 📁 Directory Structure on Server
|
||||
|
||||
### Main Project Locations
|
||||
|
||||
```
|
||||
/opt/hosting-platform/
|
||||
/opt/hosting-platform/ # 🎯 CUSTOMER PANEL (Main Project)
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── main.py
|
||||
│ │ ├── config.py
|
||||
│ │ ├── main.py # Flask app entry point
|
||||
│ │ ├── config.py # Configuration
|
||||
│ │ ├── models/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ └── domain.py
|
||||
│ │ ├── services/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ └── cloudflare_service.py
|
||||
│ │ └── api/
|
||||
│ ├── venv/
|
||||
│ │ │ ├── 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/
|
||||
│ │ ├── App.jsx
|
||||
│ │ ├── main.jsx
|
||||
│ │ ├── pages/
|
||||
│ │ │ ├── DomainSetup.jsx
|
||||
│ │ │ └── DomainList.jsx
|
||||
│ │ │ ├── Dashboard.jsx
|
||||
│ │ │ ├── DomainList.jsx
|
||||
│ │ │ └── AdminCFAccounts.jsx
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── AddDomainWizard.jsx
|
||||
│ │ │ ├── CFAccountModal.jsx
|
||||
│ │ │ └── NSInstructions.jsx
|
||||
│ │ └── services/
|
||||
│ │ └── api.js
|
||||
│ │ └── api.js # API client
|
||||
│ ├── node_modules/
|
||||
│ ├── package.json
|
||||
│ └── vite.config.js
|
||||
└── deploy.sh
|
||||
└── .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/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Auto-Deploy Workflow
|
||||
## ⚙️ Services & Process Management
|
||||
|
||||
1. **Developer pushes code** to `main` branch
|
||||
2. **Gitea webhook** triggers → `POST http://176.96.129.77:5000/webhook/deploy`
|
||||
3. **Backend receives webhook** → Executes `/opt/hosting-platform/deploy.sh`
|
||||
4. **Deploy script**:
|
||||
- Pulls latest code from Git
|
||||
- Installs dependencies
|
||||
- Restarts services via Supervisor
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -170,16 +365,54 @@ tail -f /var/log/nginx/access.log
|
|||
tail -f /var/log/nginx/error.log
|
||||
```
|
||||
|
||||
### Database
|
||||
### Database Management
|
||||
|
||||
```bash
|
||||
# Connect to PostgreSQL
|
||||
psql -U hosting_user -d hosting_db
|
||||
# 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
|
||||
|
|
@ -217,41 +450,205 @@ openssl s_client -connect argeict.net:443 -servername argeict.net < /dev/null 2>
|
|||
|
||||
---
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
## 🆘 Troubleshooting Guide
|
||||
|
||||
### ❌ Backend Not Starting
|
||||
|
||||
### Backend not starting
|
||||
```bash
|
||||
# Check logs
|
||||
# 1. Check logs
|
||||
tail -f /var/log/hosting-backend.log
|
||||
tail -f /var/log/admin-backend.log
|
||||
|
||||
# Check if port is in use
|
||||
# 2. Check if port is in use
|
||||
lsof -i :5000
|
||||
lsof -i :5001
|
||||
|
||||
# Restart
|
||||
# 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
|
||||
### ❌ Frontend Not Loading
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
# 1. Check logs
|
||||
tail -f /var/log/hosting-frontend.log
|
||||
|
||||
# Restart
|
||||
# 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
|
||||
### ❌ Database Connection Issues
|
||||
|
||||
```bash
|
||||
# Check PostgreSQL status
|
||||
# 1. Check PostgreSQL status
|
||||
systemctl status postgresql
|
||||
|
||||
# Check connections
|
||||
psql -U hosting_user -d hosting_db -c "SELECT * FROM pg_stat_activity;"
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Deployment Date**: 2026-01-10
|
||||
**Version**: 1.0.0
|
||||
**Deployed By**: Hosting Platform Team
|
||||
## 📊 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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue