mirror of
https://github.com/Grace-Solutions/Depl0y-Custom.git
synced 2026-07-26 11:28:19 +00:00
Initial Commit
This commit is contained in:
Alphaeus Mote
@@ -0,0 +1,571 @@
|
||||
# Depl0y Deployment Guide
|
||||
|
||||
This guide covers how to deploy Depl0y updates, make code changes, and manage the production environment.
|
||||
|
||||
## Table of Contents
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Making Code Changes](#making-code-changes)
|
||||
- [Deploying Changes](#deploying-changes)
|
||||
- [Creating a Release](#creating-a-release)
|
||||
- [Update Distribution](#update-distribution)
|
||||
- [Rollback Procedures](#rollback-procedures)
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
/home/administrator/depl0y/ # Development directory
|
||||
├── backend/ # Python FastAPI backend
|
||||
│ ├── app/
|
||||
│ │ ├── api/ # API endpoints
|
||||
│ │ ├── core/ # Core functionality
|
||||
│ │ ├── models/ # Database models
|
||||
│ │ └── services/ # Business logic
|
||||
│ ├── requirements.txt
|
||||
│ └── main.py
|
||||
├── frontend/ # Vue.js frontend
|
||||
│ ├── src/
|
||||
│ │ ├── views/ # Page components
|
||||
│ │ ├── services/ # API services
|
||||
│ │ ├── store/ # State management
|
||||
│ │ └── router/ # Routes
|
||||
│ ├── package.json
|
||||
│ └── vite.config.js
|
||||
├── scripts/ # Deployment scripts
|
||||
├── install.sh # One-line installer
|
||||
└── *.md # Documentation
|
||||
|
||||
/opt/depl0y/ # Production directory
|
||||
├── backend/ # Production backend
|
||||
├── frontend/dist/ # Built frontend assets
|
||||
└── ...
|
||||
|
||||
/var/lib/depl0y/ # Data directory
|
||||
├── db/ # SQLite database
|
||||
├── isos/ # ISO images
|
||||
├── cloud-images/ # Cloud image cache
|
||||
└── ssh_keys/ # SSH keys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Making Code Changes
|
||||
|
||||
### Backend Changes
|
||||
|
||||
1. **Edit Backend Code**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/backend
|
||||
# Edit files in app/ directory
|
||||
```
|
||||
|
||||
2. **Test Changes Locally (Optional)**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --host 127.0.0.1 --port 8001
|
||||
```
|
||||
|
||||
3. **Check Logs**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -f
|
||||
```
|
||||
|
||||
### Frontend Changes
|
||||
|
||||
1. **Edit Frontend Code**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/frontend
|
||||
# Edit files in src/ directory
|
||||
```
|
||||
|
||||
2. **Test Changes Locally (Optional)**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run dev
|
||||
# Access at http://localhost:5173
|
||||
```
|
||||
|
||||
3. **Check Console**
|
||||
- Open browser Developer Tools (F12)
|
||||
- Check Console for errors
|
||||
- Check Network tab for API calls
|
||||
|
||||
---
|
||||
|
||||
## Deploying Changes
|
||||
|
||||
### Quick Deploy Script
|
||||
|
||||
Create a deployment script for convenience:
|
||||
|
||||
```bash
|
||||
cat > /home/administrator/depl0y/deploy.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🚀 Deploying Depl0y..."
|
||||
|
||||
# Build frontend
|
||||
echo "📦 Building frontend..."
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Deploy frontend
|
||||
echo "📤 Deploying frontend..."
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
|
||||
# Deploy backend
|
||||
echo "📤 Deploying backend..."
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chmod -R 755 /opt/depl0y/backend
|
||||
|
||||
# Restart services
|
||||
echo "🔄 Restarting services..."
|
||||
sudo systemctl restart depl0y-backend
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Check status
|
||||
echo "✅ Checking status..."
|
||||
sleep 2
|
||||
sudo systemctl status depl0y-backend --no-pager | head -15
|
||||
|
||||
echo ""
|
||||
echo "✅ Deployment complete!"
|
||||
echo "Check logs: sudo journalctl -u depl0y-backend -f"
|
||||
EOF
|
||||
|
||||
chmod +x /home/administrator/depl0y/deploy.sh
|
||||
```
|
||||
|
||||
### Deploy with Script
|
||||
|
||||
```bash
|
||||
/home/administrator/depl0y/deploy.sh
|
||||
```
|
||||
|
||||
### Manual Deployment Steps
|
||||
|
||||
#### Deploy Backend Only
|
||||
|
||||
```bash
|
||||
# Copy backend files to production
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/
|
||||
|
||||
# Fix permissions
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chmod -R 755 /opt/depl0y/backend
|
||||
|
||||
# Restart backend service
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Check status
|
||||
sudo systemctl status depl0y-backend
|
||||
sudo journalctl -u depl0y-backend -n 50
|
||||
```
|
||||
|
||||
#### Deploy Frontend Only
|
||||
|
||||
```bash
|
||||
# Build frontend
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Deploy to production
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
|
||||
# Fix permissions
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
|
||||
# Reload nginx (optional, usually not needed)
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
#### Deploy Both (Full Deploy)
|
||||
|
||||
```bash
|
||||
# Build frontend
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Deploy frontend
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
|
||||
# Deploy backend
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chmod -R 755 /opt/depl0y/backend
|
||||
|
||||
# Restart services
|
||||
sudo systemctl restart depl0y-backend
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Verify
|
||||
sudo systemctl status depl0y-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating a Release
|
||||
|
||||
### 1. Update Version Number
|
||||
|
||||
Edit the version in the backend config:
|
||||
|
||||
```bash
|
||||
nano /home/administrator/depl0y/backend/app/core/config.py
|
||||
```
|
||||
|
||||
Change:
|
||||
```python
|
||||
APP_VERSION: str = "1.1.0" # Update this
|
||||
```
|
||||
|
||||
### 2. Update Release Notes
|
||||
|
||||
Edit the system updates endpoint:
|
||||
|
||||
```bash
|
||||
nano /home/administrator/depl0y/backend/app/api/system_updates.py
|
||||
```
|
||||
|
||||
Update the `release_notes` in the `/version` endpoint:
|
||||
```python
|
||||
"release_notes": f"""
|
||||
Depl0y {settings.APP_VERSION} Release Notes:
|
||||
|
||||
✨ New Features:
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
🔧 Improvements:
|
||||
- Improvement 1
|
||||
- Improvement 2
|
||||
|
||||
🐛 Bug Fixes:
|
||||
- Fix 1
|
||||
- Fix 2
|
||||
"""
|
||||
```
|
||||
|
||||
### 3. Deploy to Production
|
||||
|
||||
```bash
|
||||
/home/administrator/depl0y/deploy.sh
|
||||
```
|
||||
|
||||
### 4. Test Update Endpoint
|
||||
|
||||
```bash
|
||||
curl http://localhost/api/v1/system-updates/version
|
||||
```
|
||||
|
||||
Verify the version and release notes are correct.
|
||||
|
||||
---
|
||||
|
||||
## Update Distribution
|
||||
|
||||
Depl0y uses a **pull-based update system** where client instances pull updates from the main server (`deploy.agit8or.net`).
|
||||
|
||||
### How Updates Work
|
||||
|
||||
1. **Main Server** (deploy.agit8or.net)
|
||||
- Serves version information via `/api/v1/system-updates/version`
|
||||
- Provides update packages via `/api/v1/system-updates/download`
|
||||
- Hosts the installer via `/install.sh`
|
||||
|
||||
2. **Client Instances**
|
||||
- Check for updates by querying main server
|
||||
- Compare local version with latest version
|
||||
- Download and apply updates if available
|
||||
|
||||
### Making Main Server the Update Source
|
||||
|
||||
If this is your main update server (`deploy.agit8or.net`):
|
||||
|
||||
1. **Ensure the installer is accessible**
|
||||
```bash
|
||||
# The installer should be served by nginx
|
||||
curl http://deploy.agit8or.net/install.sh
|
||||
```
|
||||
|
||||
2. **Update the backend config if needed**
|
||||
```bash
|
||||
nano /home/administrator/depl0y/backend/app/api/system_updates.py
|
||||
```
|
||||
|
||||
Verify:
|
||||
```python
|
||||
UPDATE_SERVER = "http://deploy.agit8or.net"
|
||||
```
|
||||
|
||||
3. **Test the update endpoints**
|
||||
```bash
|
||||
# Version info
|
||||
curl http://deploy.agit8or.net/api/v1/system-updates/version
|
||||
|
||||
# Download package (requires auth)
|
||||
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
||||
http://deploy.agit8or.net/api/v1/system-updates/download \
|
||||
-o test-package.tar.gz
|
||||
```
|
||||
|
||||
### Client Update Process
|
||||
|
||||
When a client checks for updates (Settings → System Updates):
|
||||
|
||||
1. Client calls `/api/v1/system-updates/check`
|
||||
2. Backend queries main server at `http://deploy.agit8or.net/api/v1/system-updates/version`
|
||||
3. Compares versions
|
||||
4. If update available, shows "Install Update" button
|
||||
5. When clicked, downloads from `http://deploy.agit8or.net/api/v1/system-updates/download`
|
||||
6. Extracts, builds, deploys, and restarts
|
||||
|
||||
---
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
The update system creates automatic backups at:
|
||||
```
|
||||
/opt/depl0y-backups/backup-YYYYMMDD-HHMMSS/
|
||||
```
|
||||
|
||||
### Manual Rollback
|
||||
|
||||
1. **Stop the service**
|
||||
```bash
|
||||
sudo systemctl stop depl0y-backend
|
||||
```
|
||||
|
||||
2. **Restore from backup**
|
||||
```bash
|
||||
# Find latest backup
|
||||
ls -la /opt/depl0y-backups/
|
||||
|
||||
# Restore backend
|
||||
sudo cp -r /opt/depl0y-backups/backup-YYYYMMDD-HHMMSS/backend/* /opt/depl0y/backend/
|
||||
|
||||
# Restore frontend (if backed up)
|
||||
sudo cp -r /opt/depl0y-backups/backup-YYYYMMDD-HHMMSS/frontend/* /opt/depl0y/frontend/
|
||||
```
|
||||
|
||||
3. **Fix permissions**
|
||||
```bash
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
```
|
||||
|
||||
4. **Restart service**
|
||||
```bash
|
||||
sudo systemctl start depl0y-backend
|
||||
sudo systemctl status depl0y-backend
|
||||
```
|
||||
|
||||
### Manual Backup Before Changes
|
||||
|
||||
```bash
|
||||
# Create backup directory
|
||||
BACKUP_DIR="/opt/depl0y-backups/manual-$(date +%Y%m%d-%H%M%S)"
|
||||
sudo mkdir -p "$BACKUP_DIR"
|
||||
|
||||
# Backup backend
|
||||
sudo cp -r /opt/depl0y/backend "$BACKUP_DIR/"
|
||||
|
||||
# Backup frontend
|
||||
sudo cp -r /opt/depl0y/frontend "$BACKUP_DIR/"
|
||||
|
||||
# Backup database
|
||||
sudo cp -r /var/lib/depl0y/db "$BACKUP_DIR/"
|
||||
|
||||
echo "Backup created at $BACKUP_DIR"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Deployment Issues
|
||||
|
||||
### Issue: Backend Service Won't Start
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -n 100
|
||||
```
|
||||
|
||||
**Common causes:**
|
||||
- Python syntax errors
|
||||
- Missing dependencies
|
||||
- Database connection issues
|
||||
- Port already in use
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check if port 8000 is in use
|
||||
sudo lsof -i :8000
|
||||
|
||||
# Reinstall dependencies if needed
|
||||
cd /opt/depl0y/backend
|
||||
sudo -u depl0y venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Issue: Frontend Shows Blank Page
|
||||
|
||||
**Check:**
|
||||
1. Browser console (F12) for JavaScript errors
|
||||
2. Nginx error logs: `sudo tail -f /var/log/nginx/depl0y_error.log`
|
||||
3. Verify build was successful
|
||||
4. Check file permissions
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Rebuild and redeploy
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
```
|
||||
|
||||
### Issue: API Calls Failing (500 Errors)
|
||||
|
||||
**Check backend logs:**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -f
|
||||
```
|
||||
|
||||
**Common causes:**
|
||||
- Backend crashed
|
||||
- Database errors
|
||||
- API endpoint errors
|
||||
|
||||
**Quick restart:**
|
||||
```bash
|
||||
sudo systemctl restart depl0y-backend
|
||||
```
|
||||
|
||||
### Issue: Changes Not Appearing
|
||||
|
||||
**For backend:**
|
||||
```bash
|
||||
# Make sure you restarted the service
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Verify files were copied
|
||||
ls -la /opt/depl0y/backend/app/api/
|
||||
```
|
||||
|
||||
**For frontend:**
|
||||
```bash
|
||||
# Make sure you rebuilt
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Verify files were copied
|
||||
ls -la /opt/depl0y/frontend/dist/
|
||||
|
||||
# Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring and Maintenance
|
||||
|
||||
### Check Service Status
|
||||
```bash
|
||||
sudo systemctl status depl0y-backend
|
||||
sudo systemctl status nginx
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Live backend logs
|
||||
sudo journalctl -u depl0y-backend -f
|
||||
|
||||
# Last 100 lines
|
||||
sudo journalctl -u depl0y-backend -n 100
|
||||
|
||||
# Nginx access logs
|
||||
sudo tail -f /var/log/nginx/depl0y_access.log
|
||||
|
||||
# Nginx error logs
|
||||
sudo tail -f /var/log/nginx/depl0y_error.log
|
||||
```
|
||||
|
||||
### Restart Services
|
||||
```bash
|
||||
# Backend only
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Nginx only
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Both
|
||||
sudo systemctl restart depl0y-backend
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### Check Disk Space
|
||||
```bash
|
||||
df -h /opt/depl0y
|
||||
df -h /var/lib/depl0y
|
||||
```
|
||||
|
||||
### Clean Up Old Backups
|
||||
```bash
|
||||
# List backups
|
||||
ls -lah /opt/depl0y-backups/
|
||||
|
||||
# Remove old backups (keep last 5)
|
||||
cd /opt/depl0y-backups/
|
||||
ls -t | tail -n +6 | xargs sudo rm -rf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Deploy Everything
|
||||
```bash
|
||||
cd /home/administrator/depl0y/frontend && npm run build && \
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/* && \
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/ && \
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/ && \
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist && \
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend && \
|
||||
sudo systemctl restart depl0y-backend
|
||||
```
|
||||
|
||||
### Check Everything
|
||||
```bash
|
||||
sudo systemctl status depl0y-backend nginx && \
|
||||
curl -s http://localhost/api/v1/system-updates/version | head -5 && \
|
||||
sudo journalctl -u depl0y-backend -n 10
|
||||
```
|
||||
|
||||
### Emergency Restart
|
||||
```bash
|
||||
sudo systemctl restart depl0y-backend nginx && \
|
||||
sleep 2 && \
|
||||
sudo systemctl status depl0y-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**For more information, see:**
|
||||
- [INSTALL.md](INSTALL.md) - Installation guide
|
||||
- [README.md](README.md) - Project overview
|
||||
- [CLOUD_IMAGES_GUIDE.md](CLOUD_IMAGES_GUIDE.md) - Cloud images setup
|
||||
Reference in New Issue
Block a user