Skip to content

DEPLOYMENT_WORKFLOW.md

Latest commit

 

History

History
390 lines (298 loc) · 10.1 KB

DEPLOYMENT_WORKFLOW.md

File metadata and controls

390 lines (298 loc) · 10.1 KB

oaDeviceAPI Deployment Workflow Guide

Purpose: Streamlined deployment guide for oaDeviceAPI unified device management service.

Target Audience: DevOps engineers, system administrators, and deployment teams.

🚀 Overview

oaDeviceAPI is a unified device management service that provides consistent APIs across macOS and OrangePi platforms with automatic platform detection and standardized device metrics collection.

System Architecture

  • FastAPI Backend: Python-based REST API service (Port 8000)
  • Platform Detection: Automatic macOS/OrangePi identification
  • Device Metrics: CPU, memory, disk, network monitoring
  • Service Integration: Tailscale networking and health monitoring

📋 Prerequisites

System Requirements

Hardware Requirements:

  • Minimum: 2 CPU cores, 4GB RAM, 20GB storage
  • Recommended: 4 CPU cores, 8GB RAM, 50GB storage
  • Network: Stable internet connection for Tailscale

Software Requirements:

  • Operating System: macOS 13+ or Ubuntu 20.04+
  • Python: Version 3.12+ with uv package manager
  • Tailscale: Installed and authenticated
  • Git: Version 2.30+ for repository operations

Dependencies

System Dependencies:

  • Python 3.12+ with uv package manager
  • Tailscale client for networking
  • system services (systemd/LaunchAgent)

Python Dependencies:

  • FastAPI for API framework
  • psutil for system metrics
  • pydantic for data validation
  • requests for HTTP client operations

🛠️ Deployment Methods

Ansible Deployment (Recommended)

Deployment through oaDashboard:

  1. Access oaDashboard deployment interface
  2. Select target devices and oaDeviceAPI component
  3. Configure deployment parameters
  4. Execute deployment with real-time monitoring
  5. Validate service health and connectivity

Direct Ansible Execution:

# Deploy to specific inventory
ansible-playbook playbooks/deploy-oadeviceapi.yml \
  -i inventory/production \
  -e "target_hosts=device_group"

# Deploy with custom configuration
ansible-playbook playbooks/deploy-oadeviceapi.yml \
  -i inventory/production \
  -e "api_port=9090" \
  -e "enable_tailscale=true"

Manual Deployment

Development Setup:

# Clone and setup repository
git clone https://github.com/orangead/oaPangaea.git
cd oaPangaea/oaDeviceAPI

# Setup Python environment
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with appropriate settings

# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Production Setup:

# System service installation
sudo cp scripts/oadeviceapi.service /etc/systemd/system/
sudo systemctl enable oadeviceapi
sudo systemctl start oadeviceapi

# Service status check
sudo systemctl status oadeviceapi

🔧 Configuration Management

Environment Configuration

Core Environment Variables:

# Service Configuration
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4
DEBUG=false

# Platform Detection
PLATFORM_AUTO_DETECT=true
PLATFORM_OVERRIDE=  # Optional: macos, ubuntu, or orangepi

# Tailscale Integration
TAILSCALE_ENABLE=true
TAILSCALE_API_KEY=your-tailscale-api-key
TAILSCALE_TAILNET=your-tailnet-name

# Security
API_SECRET_KEY=your-secret-key
CORS_ORIGINS=["http://localhost:3000"]

Platform-Specific Configuration:

# macOS Configuration
MACOS_SERVICE_USER=orangead
MACOS_LOG_PATH=/var/log/orangead/oadeviceapi.log

# Ubuntu/OrangePi Configuration
UBUNTU_SERVICE_USER=orangead
UBUNTU_LOG_PATH=/var/log/oadeviceapi/app.log
UBUNTU_CONFIG_PATH=/etc/oadeviceapi/

Service Registration

macOS LaunchAgent Configuration:

<!-- ~/Library/LaunchAgents/com.orangead.oadeviceapi.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.orangead.oadeviceapi</string>
    <key>ProgramArguments</key>
    <array>
      <string>/opt/oaDeviceAPI/.venv/bin/python</string>
      <string>-m</string>
      <string>uvicorn</string>
      <string>app.main:app</string>
      <string>--host</string>
      <string>0.0.0.0</string>
      <string>--port</string>
      <string>8000</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
  </dict>
</plist>

Ubuntu systemd Service Configuration:

[Unit]
Description=oaDeviceAPI Service
After=network.target

[Service]
Type=simple
User=orangead
WorkingDirectory=/opt/oaDeviceAPI
Environment=PATH=/opt/oaDeviceAPI/.venv/bin
ExecStart=/opt/oaDeviceAPI/.venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

🔍 Platform Detection and Integration

Automatic Platform Detection

graph TB
    START([Service Start]) --> DETECT{Platform Detection}
    
    DETECT -->|macOS| MACOS[macOS Handler]
    DETECT -->|Ubuntu| UBUNTU[Ubuntu Handler] 
    DETECT -->|OrangePi| ORANGEPI[OrangePi Handler]
    
    MACOS --> MACMETRICS[macOS Metrics Collection]
    UBUNTU --> UBUNTUMETRICS[Ubuntu Metrics Collection]
    ORANGEPI --> ORANGEPIMETRICS[OrangePi Metrics Collection]
    
    MACMETRICS --> API[Unified API Response]
    UBUNTUMETRICS --> API
    ORANGEPIMETRICS --> API
    
    API --> END([Service Ready])
Loading

Metrics Collection

Unified Metrics API:

  • System Information: Platform, hostname, OS version
  • CPU Metrics: Usage percentage, load average, core count
  • Memory Metrics: Usage percentage, available memory, swap usage
  • Disk Metrics: Usage percentage, disk I/O, mount points
  • Network Metrics: Interface statistics, bandwidth usage
  • Process Metrics: Running processes, service status

Platform-Specific Features:

  • macOS: LaunchAgent integration, macOS-specific system metrics
  • Ubuntu: systemd integration, Linux performance counters
  • OrangePi: ARM64 optimizations, device-specific sensors

🔌 API Integration

Core API Endpoints

Device Information:

  • GET / - Service health and version information
  • GET /device - Device platform and system information
  • GET /device/metrics - Current system metrics
  • WebSocket /ws/metrics - Real-time metrics streaming

Health and Status:

  • GET /health - Service health check
  • GET /status - Detailed service status
  • GET /platform - Platform detection results

Device Control:

  • POST /device/restart - Restart device services
  • POST /device/shutdown - Shutdown device (with authentication)
  • POST /device/update - Trigger system updates

Integration Examples

Metrics Collection Integration:

import requests

# Get device metrics
response = requests.get("http://device-api:8000/device/metrics")
metrics = response.json()

# Monitor CPU usage
cpu_usage = metrics["cpu"]["usage_percent"]
if cpu_usage > 80:
    print("High CPU usage detected")

Real-time Monitoring:

import websocket
import json

def on_message(ws, message):
    metrics = json.loads(message)
    print(f"CPU: {metrics['cpu']['usage_percent']}%")

ws = websocket.WebSocketApp("ws://device-api:8000/ws/metrics")
ws.on_message = on_message
ws.run_forever()

🔍 Monitoring and Troubleshooting

Health Monitoring

Service Health Checks:

  • API Endpoint: /health for basic service status
  • Metrics Endpoint: /device/metrics for system health
  • Dependency Checks: Tailscale connectivity, system resources
  • Performance Monitoring: Response times, error rates

Monitoring Integration:

# Prometheus metrics configuration
scrape_configs:
  - job_name: 'oadeviceapi'
    static_configs:
      - targets: ['device-api:8000']
    metrics_path: '/metrics'
    scrape_interval: 30s

Common Issues and Solutions

Service Startup Issues:

  • Port Conflicts: Check if port 8000 is available
  • Permission Issues: Verify user permissions for service files
  • Environment Variables: Validate configuration settings
  • Dependencies: Ensure Python environment and packages are installed

Performance Issues:

  • High Memory Usage: Monitor memory usage and optimize
  • Slow Response Times: Check system resource utilization
  • Network Issues: Verify Tailscale connectivity

Troubleshooting Commands:

# Check service status (systemd)
systemctl status oadeviceapi

# Check service status (LaunchAgent)
launchctl list | grep oadeviceapi

# Check service logs
journalctl -u oadeviceapi -f

# Test API connectivity
curl http://localhost:8000/health

# Check metrics endpoint
curl http://localhost:8000/device/metrics

📚 Reference Documentation

Implementation Files

Core Application Files:

  • app/main.py - FastAPI application entry point
  • app/models/ - Data models and schemas
  • app/routers/ - API route definitions
  • app/services/ - Platform-specific services

Configuration Files:

  • .env.example - Environment variable template
  • scripts/ - Deployment and maintenance scripts
  • config/ - Configuration templates

Deployment Files:

  • Dockerfile - Container deployment configuration
  • docker-compose.yml - Multi-container deployment
  • requirements.txt - Python dependencies

API Documentation

Interactive API Documentation:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
  • OpenAPI Spec: http://localhost:8000/openapi.json

External Integration:

  • oaDashboard: ../oaDashboard/INTEGRATION_GUIDE.md
  • oaAnsible: ../oaAnsible/DEPLOYMENT_WORKFLOW.md
  • System Architecture: ../SYSTEM_INTEGRATION.md

Deployment Quick Reference:

  1. Ansible: Use oaDashboard or direct ansible-playbook execution
  2. Manual: Clone repository, setup Python environment, configure service
  3. Validation: Test /health and /device/metrics endpoints
  4. Monitoring: Set up health checks and metrics collection
  5. Integration: Connect to oaDashboard for device monitoring

Support: For deployment issues, consult troubleshooting section or refer to component-specific documentation.