mirror of
https://github.com/Grace-Solutions/Depl0y-Custom.git
synced 2026-07-26 11:28:19 +00:00
Alphaeus Mote
572 lines
13 KiB
Markdown
572 lines
13 KiB
Markdown
# 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
|