hostadmin
/
hosting-platform
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update DEPLOYMENT.md with complete architecture and process documentation

This commit is contained in:
oguz ozturk 2026-01-12 16:39:52 +03:00
parent 84c8cb728e
commit 9a2f47ee57
1 changed files with 452 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

507
DEPLOYMENT.md
View File

@ -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 Information
**Server IP**: `176.96.129.77` **Server IP**: `176.96.129.77`
**SSH Access**: `ssh -i ~/.ssh/id_rsa root@176.96.129.77`
**OS**: Ubuntu 24.04 LTS **OS**: Ubuntu 24.04 LTS
**RAM**: 4GB **RAM**: 4GB
**CPU**: 4 cores **CPU**: 4 cores
**Process Manager**: Supervisor (supervisord)
--- ---
## 🌐 Production URLs ## 🌐 Production URLs
| Service | URL | Status | | Service | URL | Port | Status |
|---------|-----|--------| |---------|-----|------|--------|
| **Frontend** | https://argeict.net | ✅ Running | | **Customer Panel** | https://panel.argeict.net | 3001 | ✅ Running |
| **Backend API** | https://api.argeict.net | ✅ Running | | **Admin Panel** | https://admin.argeict.net | 5001 | ✅ Running |
| **Gitea** | https://gitea.argeict.net | ✅ 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 (HTTPS)** | 443 | - | ✅ Running |
| **Nginx (HTTP → HTTPS)** | 80 | - | ✅ Running | | **Nginx (HTTP → HTTPS)** | 80 | - | ✅ Running |
### 🔐 Credentials ### 🔐 Credentials & Access
**Gitea Admin**: **Gitea Admin**:
- Username: `hostadmin` - Username: `hostadmin`
@ -41,9 +50,11 @@
- Repository: https://gitea.argeict.net/hostadmin/hosting-platform - Repository: https://gitea.argeict.net/hostadmin/hosting-platform
**PostgreSQL**: **PostgreSQL**:
- User: `hosting_user` - User: `hosting` (main user)
- Password: `HostingDB2024!` - Database Names:
- Database: `hosting_db` - `hosting` - Customer panel database
- `admin_hosting_db` - Admin panel database
- Access: `sudo -u postgres psql -d hosting`
**Redis**: **Redis**:
- No password (localhost only) - No password (localhost only)
@ -51,7 +62,7 @@
**SSL Certificates (Let's Encrypt)**: **SSL Certificates (Let's Encrypt)**:
- Certificate: `/etc/letsencrypt/live/argeict.net/fullchain.pem` - Certificate: `/etc/letsencrypt/live/argeict.net/fullchain.pem`
- Private Key: `/etc/letsencrypt/live/argeict.net/privkey.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) - 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/ ├── backend/
│ ├── app/ │ ├── app/
│ │ ├── __init__.py │ │ ├── main.py # Flask app entry point
│ │ ├── main.py │ │ ├── config.py # Configuration
│ │ ├── config.py
│ │ ├── models/ │ │ ├── models/
│ │ │ ├── __init__.py │ │ │ ├── domain.py # Domain model
│ │ │ └── domain.py │ │ │ └── customer.py # Customer model
│ │ ├── services/ │ │ ├── routes/
│ │ │ ├── __init__.py │ │ │ ├── admin.py # Admin API routes
│ │ │ └── cloudflare_service.py │ │ │ └── customer.py # Customer API routes
│ │ └── api/ │ │ ├── utils/
│ ├── venv/ │ │ │ ├── cloudflare.py # CF API integration
│ │ │ └── crypto.py # Encryption utilities
│ │ └── services/
│ ├── venv/ # Python virtual environment
│ ├── migrations/ # Database migration scripts
│ └── requirements.txt │ └── requirements.txt
├── frontend/ ├── frontend/
│ ├── src/ │ ├── src/
│ │ ├── App.jsx
│ │ ├── main.jsx
│ │ ├── pages/ │ │ ├── pages/
│ │ │ ├── DomainSetup.jsx │ │ │ ├── Dashboard.jsx
│ │ │ └── DomainList.jsx │ │ │ ├── DomainList.jsx
│ │ │ └── AdminCFAccounts.jsx
│ │ ├── components/
│ │ │ ├── AddDomainWizard.jsx
│ │ │ ├── CFAccountModal.jsx
│ │ │ └── NSInstructions.jsx
│ │ └── services/ │ │ └── services/
│ │ └── api.js │ │ └── api.js # API client
│ ├── node_modules/
│ ├── package.json │ ├── package.json
│ └── vite.config.js │ └── 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 ### Supervisor Services
2. **Gitea webhook** triggers → `POST http://176.96.129.77:5000/webhook/deploy`
3. **Backend receives webhook** → Executes `/opt/hosting-platform/deploy.sh` Supervisor manages backend and frontend processes. Configuration: `/etc/supervisor/conf.d/`
4. **Deploy script**:
- Pulls latest code from Git **Check all services**:
- Installs dependencies ```bash
- Restarts services via Supervisor 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 tail -f /var/log/nginx/error.log
``` ```
### Database ### Database Management
```bash ```bash
# Connect to PostgreSQL # List all databases
psql -U hosting_user -d hosting_db 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 # Connect to Redis
redis-cli 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 ## 🧪 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 ```bash
# Check logs # 1. Check logs
tail -f /var/log/hosting-backend.log 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 :5000
lsof -i :5001
# Restart # 3. Check supervisor status
supervisorctl status
# 4. Restart service
supervisorctl restart hosting-backend 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 ```bash
# Check logs # 1. Check logs
tail -f /var/log/hosting-frontend.log 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 supervisorctl restart hosting-frontend
# 5. Check Nginx
nginx -t
systemctl status nginx
``` ```
### Database connection issues ### ❌ Database Connection Issues
```bash ```bash
# Check PostgreSQL status # 1. Check PostgreSQL status
systemctl status postgresql systemctl status postgresql
# Check connections # 2. Check if database exists
psql -U hosting_user -d hosting_db -c "SELECT * FROM pg_stat_activity;" 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 ## 📊 Quick Reference Commands
**Version**: 1.0.0
**Deployed By**: Hosting Platform Team ### 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