# GigLez - Quick Start Guide

## 🚀 Installation (One Command)

```bash
./scripts/safe_install.sh --create-venv && source venv/bin/activate && ./scripts/safe_install.sh --all
```

That's it! Everything is installed and ready.

---

## 📦 Safe Package Installation

### Why Regular `pip install` Might Not Work

Common issues:
- ❌ No virtual environment (installs system-wide, permission errors)
- ❌ Old pip version (compatibility issues)
- ❌ Dependency conflicts (breaks existing packages)
- ❌ No rollback (can't undo if something breaks)

### Solution: Use Our Safe Install Script

✅ Auto-creates/activates virtual environment
✅ Checks for conflicts before installing
✅ Creates backups automatically
✅ Can rollback if something goes wrong
✅ Upgrades pip automatically
✅ Verifies installation success

---

## Common Commands

### First Time Setup

```bash
# 1. Create virtual environment
./scripts/safe_install.sh --create-venv

# 2. Activate it
source venv/bin/activate

# 3. Install all dependencies
./scripts/safe_install.sh --all
```

### Daily Use

```bash
# Activate virtual environment (every time you work)
source venv/bin/activate

# Verify environment
./scripts/safe_install.sh --check
```

### Installing Packages

```bash
# Install single package (safe way)
./scripts/safe_install.sh package_name

# Install specific version
./scripts/safe_install.sh package_name 2.0.0

# Example: Install psycopg2
./scripts/safe_install.sh psycopg2-binary
```

### Troubleshooting

```bash
# Check what's installed
pip list

# Check for package conflicts
pip check

# Create backup before making changes
./scripts/safe_install.sh --backup

# If something breaks, rollback
./scripts/safe_install.sh --rollback .pip_backups/installed_packages_YYYYMMDD_HHMMSS.txt
```

---

## Why This Works When Regular pip Doesn't

### Problem: "pip: command not found"

**Regular way (fails):**
```bash
pip install something  # Error: command not found
```

**Our way (works):**
```bash
./scripts/safe_install.sh something
# Script checks for pip, installs if missing, then installs package
```

### Problem: "Permission denied"

**Regular way (fails):**
```bash
pip install something  # Error: Permission denied
sudo pip install something  # BAD! Installs system-wide
```

**Our way (works):**
```bash
./scripts/safe_install.sh something
# Script creates/uses virtual environment, no sudo needed
```

### Problem: "Dependency conflict"

**Regular way (fails):**
```bash
pip install something  # Breaks existing packages silently
```

**Our way (works):**
```bash
./scripts/safe_install.sh something
# Script checks for conflicts, backs up, asks confirmation
```

---

## Manual Alternative (If Script Doesn't Work)

### Step-by-Step

```bash
# 1. Check Python version (must be 3.9+)
python3 --version

# 2. Create virtual environment manually
python3 -m venv venv

# 3. Activate it
source venv/bin/activate

# 4. Upgrade pip
python -m pip install --upgrade pip

# 5. Install dependencies
pip install -r requirements.txt
```

### Verify Installation

```bash
# Check installed packages
pip list

# Test database connection
python3 -c "import psycopg2; print('✓ psycopg2 works')"

# Test FastAPI
python3 -c "import fastapi; print('✓ FastAPI works')"
```

---

## Common Error Messages & Fixes

### "No module named 'pip'"

```bash
# Fix:
python3 -m ensurepip --upgrade
```

### "error: externally-managed-environment"

This means your system doesn't allow global pip installs (good!). **Solution:** Use virtual environment:

```bash
./scripts/safe_install.sh --create-venv
source venv/bin/activate
./scripts/safe_install.sh --all
```

### "ERROR: Could not build wheels for psycopg2"

```bash
# Use binary version instead:
./scripts/safe_install.sh psycopg2-binary
```

### "Requirement already satisfied" but import fails

```bash
# You're using system Python instead of venv
# Fix: Deactivate and reactivate
deactivate
source venv/bin/activate
python -c "import sys; print(sys.prefix)"  # Should show venv path
```

---

## Database Setup (Quick)

```bash
# 1. Install PostgreSQL (if not installed)
sudo apt-get install postgresql postgis

# 2. Create database
sudo -u postgres psql -c "CREATE DATABASE giglez;"
sudo -u postgres psql -c "CREATE USER giglez_user WITH PASSWORD 'password';"
sudo -u postgres psql -c "GRANT ALL ON DATABASE giglez TO giglez_user;"

# 3. Configure environment
cp .env.example .env.development
nano .env.development  # Edit DATABASE_URL

# 4. Create tables
psql -U giglez_user -d giglez -f scripts/create_schema.sql
```

---

## Running the Application

```bash
# 1. Activate virtual environment
source venv/bin/activate

# 2. Start API server
uvicorn src.api.main:app --reload

# 3. Open browser
# Visit: http://localhost:8000/docs
```

---

## Quick Reference

| Task | Command |
|------|---------|
| Create venv | `./scripts/safe_install.sh --create-venv` |
| Activate venv | `source venv/bin/activate` |
| Install all deps | `./scripts/safe_install.sh --all` |
| Install one package | `./scripts/safe_install.sh package_name` |
| Check environment | `./scripts/safe_install.sh --check` |
| Create backup | `./scripts/safe_install.sh --backup` |
| List packages | `pip list` |
| Deactivate venv | `deactivate` |
| Start API server | `uvicorn src.api.main:app --reload` |

---

## Next Steps

1. ✅ Install dependencies (done if you followed above)
2. 📊 Setup database (see Database Setup section)
3. 📥 Download datasets: `./scripts/download_rf_test_datasets.sh`
4. 🗺️ Import with GPS: `./scripts/import_with_african_gps.py --limit 1000`
5. 🚀 Start server: `uvicorn src.api.main:app --reload`
6. 🌐 Visit: http://localhost:8000/docs

---

## Getting Help

```bash
# Script help
./scripts/safe_install.sh --help

# Full documentation
cat docs/INSTALLATION_GUIDE.md

# Check logs
tail -f logs/app.log
```

---

**Last Updated:** 2026-01-16
**Tested On:** Ubuntu 22.04, Python 3.9+