docs_archive/HOW_TO_START_MORPHGUARD.md

# 🚀 How to Start MorphGuard Application

## Table of Contents
- [Quick Start](#-quick-start-development)
- [Environment Variables](#-environment-variables-setup)
- [Production Mode](#-production-mode)
- [Test Mode](#-test-mode)
- [First Time Setup](#-first-time-setup-step-by-step)
- [Verification](#-verify-application-is-running)
- [Stopping the Application](#-stopping-the-application)
- [Troubleshooting](#-troubleshooting)

---

## 🚀 **Quick Start (Environment-based)**

**Recommended**: Use the environment-based startup script:

```bash
cd /root/MorphGuard

# Development mode (default)
./start_morphguard.sh

# Or explicitly specify development
./start_morphguard.sh development

# Production mode
./start_morphguard.sh production
```

**Legacy method** (manual):
```bash
cd /root/MorphGuard
python app.py
```

**Note**: Environment-based startup loads all variables from `.env.development` or `.env.production` files.

---

## 📁 **Environment Files (.env approach)**

### Available Environment Files

MorphGuard uses environment files for configuration:

- **`.env.development`** - Development settings (debugging enabled, relaxed security)
- **`.env.production`** - Production settings (optimized for deployment)
- **`.env`** - Legacy basic configuration

### Environment File Content

All variables are pre-configured in the environment files:

**Key Variables in `.env.production`:**
```bash
# Model Configuration
USE_QUANTIZED=1
GAN_CHECKPOINT_PATH=pSp/pretrained_models/psp_ffhq_inversion.pt
GAN_CONFIG_PATH=config/psp_ffhq_inversion.yaml
DETECTOR_TEMP=2.7000

# Core Settings
MORPHGUARD_SECRET_KEY=141fbd02d2a5dedb0569fc0eca7cb8fb224fe12e06f52354331f9691746a345f
MORPHGUARD_DB_NAME=morphguard
MORPHGUARD_DB_USER=morphguard
MORPHGUARD_DB_PASS=morphguard
MORPHGUARD_ETH_WALLET_ADDRESS=0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1
SOUNDCLOUD_STREAM_URL=https://soundcloud.com/juan-carlos-ricardo/sets/morphguard...
```

### Using Environment Files

```bash
# Method 1: Use the startup script (recommended)
./start_morphguard.sh production

# Method 2: Manual loading (original approach)
cd /root/MorphGuard
source venv/bin/activate
export $(grep -v '^#' .env.production | xargs)
python app.py
```

---

## 🔧 **Manual Environment Variables Setup**

### Required Environment Variables

Before starting MorphGuard, set these essential variables:

```bash
# Navigate to MorphGuard directory
cd /root/MorphGuard

# Security settings
export MORPHGUARD_SECRET_KEY="your-secret-key-$(date +%s)"

# Database configuration (TimescaleDB for AI metrics)
export MORPHGUARD_DB_USER="morphguard"
export MORPHGUARD_DB_PASS="morphguard"
export MORPHGUARD_DB_NAME="morphguard"
export MORPHGUARD_DB_HOST="localhost"
export MORPHGUARD_DB_PORT="5432"

# Blockchain integration (for verification features)
export MORPHGUARD_ETH_WALLET_ADDRESS="0x1234567890123456789012345678901234567890"
export MORPHGUARD_ETH_PRIVATE_KEY="dev-private-key"
export MORPHGUARD_ETH_ENDPOINT="http://localhost:8545"

# Landing page configuration (SoundCloud music integration)
export SOUNDCLOUD_STREAM_URL="https://soundcloud.com/juan-carlos-ricardo/sets/morphguard?si=55f2cc82203744a8a33f55218b1ea0f5&utm_source=clipboard&utm_medium=text&utm_campaign=social_sharing"

# Optional: Production mode
export FLASK_ENV="production"
export FLASK_DEBUG="false"
```

### Start with Environment Variables

```bash
python app.py
```

---

## 🏭 **Production Mode (Recommended for Deployment)**

### Option 1: Use Production Script
```bash
cd /root/MorphGuard
./start_production.sh
```

### Option 2: Systemd Service (Best for servers)
```bash
# Start the service
sudo systemctl start morphguard

# Check status
sudo systemctl status morphguard

# Enable auto-start on boot
sudo systemctl enable morphguard

# View live logs
sudo journalctl -u morphguard -f
```

### Option 3: Manual Gunicorn (Advanced)
```bash
cd /root/MorphGuard
source venv/bin/activate

gunicorn \
    --worker-class eventlet \
    -w 1 \
    --bind 0.0.0.0:5000 \
    --timeout 300 \
    --access-logfile logs/access.log \
    --error-logfile logs/error.log \
    --log-level info \
    app:app
```

---

## 🧪 **Test Mode**

To verify everything is working correctly:

```bash
cd /root/MorphGuard
./test_app.sh
```

This will:
- ✅ Test all imports and dependencies
- ✅ Verify GPU availability (RTX 5070)
- ✅ Check database connections
- ✅ Start application for 10 seconds

---

## 📋 **First Time Setup (Step-by-Step)**

### 1. Navigate to Directory
```bash
cd /root/MorphGuard
```

### 2. Set Environment Variables
```bash
export MORPHGUARD_SECRET_KEY="morphguard-secret-$(date +%s)"
export MORPHGUARD_DB_USER="morphguard"
export MORPHGUARD_DB_PASS="morphguard"
export MORPHGUARD_DB_NAME="morphguard"
export MORPHGUARD_ETH_WALLET_ADDRESS="0x1234567890123456789012345678901234567890"
export MORPHGUARD_ETH_PRIVATE_KEY="dev-private-key"
export SOUNDCLOUD_STREAM_URL="https://soundcloud.com/juan-carlos-ricardo/sets/morphguard?si=55f2cc82203744a8a33f55218b1ea0f5&utm_source=clipboard&utm_medium=text&utm_campaign=social_sharing"
```

### 3. Start Application
```bash
python app.py
```

### 4. Access Application
- **Web Interface**: http://localhost:5000
- **API Endpoints**: http://localhost:5000/api/*
- **Local Network**: http://192.168.200.102:5000

---

## 🔍 **Verify Application is Running**

### Expected Startup Output
```
⚠️ No cloud provider credentials found. Cloud features disabled.
Note: Quantization requested but CUDA available. Using GPU instead of quantized CPU model.
WebSocket support for notifications enabled.
Connecting to database morphguard on localhost:5432 as morphguard...
Schema is already at version 5, skipping setup.
Metrics collection started.
Drift watcher started.
 * Serving Flask app 'app'
 * Debug mode: off/on
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
 * Running on http://192.168.200.102:5000
```

### Health Check Commands
```bash
# Check if application is responding
curl http://localhost:5000/

# Check API status
curl http://localhost:5000/api/status

# Monitor system resources
htop

# Monitor GPU usage
watch -n 1 nvidia-smi

# Check database connection
psql -h localhost -U morphguard -d morphguard -c "SELECT version();"
```

---

## 🛑 **Stopping the Application**

### **Environment-based Startup** (Recommended)
```bash
# Method 1: Use the stop script (recommended)
./stop_morphguard.sh

# Method 2: Keyboard interrupt (if running in foreground)
Ctrl + C

# Method 3: Manual process kill
pkill -f "python app.py"
pkill -f "gunicorn.*app:app"
```

### **Systemd Service**
```bash
# Stop systemd service
sudo systemctl stop morphguard

# Disable auto-start
sudo systemctl disable morphguard
```

### **Manual Process Management**
```bash
# Find all MorphGuard processes
ps aux | grep -E "(morphguard|app\.py|gunicorn)"

# Kill specific process
kill <process_id>

# Kill all processes using port 5000
sudo kill $(sudo lsof -t -i:5000)
```

---

## 🔧 **Troubleshooting**

### Common Issues & Solutions

#### 1. **Missing Dependencies**
```bash
cd /root/MorphGuard
pip install -r requirements.txt

# Or install specific missing packages
pip install flask-socketio cryptography opencv-python pillow influxdb-client blockchain eventlet GPUtil
```

#### 2. **Database Connection Errors**
```bash
# Check if TimescaleDB/PostgreSQL is running
sudo systemctl status postgresql
sudo systemctl start postgresql

# Verify database exists
sudo -u postgres psql -c "\l" | grep morphguard

# Create database if missing
sudo -u postgres createdb morphguard
sudo -u postgres psql -c "CREATE USER morphguard WITH PASSWORD 'morphguard';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE morphguard TO morphguard;"
```

#### 3. **Permission Errors**
```bash
# Fix script permissions
chmod +x *.sh

# Fix file ownership (if needed)
sudo chown -R $USER:$USER /root/MorphGuard
```

#### 4. **Port Already in Use**
```bash
# Find process using port 5000
sudo lsof -i :5000

# Kill process using port
sudo kill $(sudo lsof -t -i:5000)

# Or use different port
export PORT=5001
python app.py
```

#### 5. **GPU Not Available**
```bash
# Check GPU status
nvidia-smi

# Verify CUDA installation
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

# Install correct PyTorch version
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
```

#### 6. **Environment Variables Not Set**
```bash
# Create environment file for persistence
cat > .env << EOF
MORPHGUARD_SECRET_KEY=morphguard-secret-$(date +%s)
MORPHGUARD_DB_USER=morphguard
MORPHGUARD_DB_PASS=morphguard
MORPHGUARD_DB_NAME=morphguard
MORPHGUARD_ETH_WALLET_ADDRESS=0x1234567890123456789012345678901234567890
MORPHGUARD_ETH_PRIVATE_KEY=dev-private-key
SOUNDCLOUD_STREAM_URL=https://soundcloud.com/juan-carlos-ricardo/sets/morphguard?si=55f2cc82203744a8a33f55218b1ea0f5&utm_source=clipboard&utm_medium=text&utm_campaign=social_sharing
EOF

# Load environment variables
source .env
```

---

## 🎯 **Quick Reference Commands**

| Action | Command |
|--------|---------|
| **Start (Development)** | `./start_morphguard.sh` |
| **Start (Production)** | `./start_morphguard.sh production` |
| **Stop Application** | `./stop_morphguard.sh` |
| **Quick Start (Legacy)** | `python app.py` |
| **Test App** | `./test_app.sh` |
| **Systemd Start** | `sudo systemctl start morphguard` |
| **Systemd Stop** | `sudo systemctl stop morphguard` |
| **Check Status** | `sudo systemctl status morphguard` |
| **View Logs** | `sudo journalctl -u morphguard -f` |
| **Access Web** | `http://localhost:5000` |
| **Check GPU** | `nvidia-smi` |
| **Check DB** | `psql -h localhost -U morphguard -d morphguard` |

---

## 🔗 **Related Files**

- **Application**: `app.py` - Main Flask application
- **Production Start**: `start_production.sh` - Production startup script
- **Deployment**: `deploy.sh` - Complete deployment automation
- **Testing**: `test_app.sh` - Application testing script
- **Dependencies**: `requirements.txt` - Python package requirements
- **User Auth**: `utils/auth.py` - SQLite user management
- **Training Metrics**: `training_db_logger.py` - TimescaleDB integration
- **Status**: `DEPLOYMENT_STATUS.md` - Complete deployment overview

---

## 📞 **Support**

If you encounter issues:

1. **Check logs**: `sudo journalctl -u morphguard -f`
2. **Verify dependencies**: `./test_app.sh`
3. **Review deployment status**: `cat DEPLOYMENT_STATUS.md`
4. **Test database connections**: Check TimescaleDB and SQLite
5. **Monitor resources**: Use `htop` and `nvidia-smi`

---

**🎉 Happy MorphGuarding! Your AI-powered morphing detection system is ready to protect against facial morphing attacks.**