giglez/QUICK_START.md

GigLez - Quick Start Guide

🚀 Installation (One Command)

./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

# 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

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

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

Installing Packages

# 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

# 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):

pip install something  # Error: command not found

Our way (works):

./scripts/safe_install.sh something
# Script checks for pip, installs if missing, then installs package

Problem: "Permission denied"

Regular way (fails):

pip install something  # Error: Permission denied
sudo pip install something  # BAD! Installs system-wide

Our way (works):

./scripts/safe_install.sh something
# Script creates/uses virtual environment, no sudo needed

Problem: "Dependency conflict"

Regular way (fails):

pip install something  # Breaks existing packages silently

Our way (works):

./scripts/safe_install.sh something
# Script checks for conflicts, backs up, asks confirmation

---

Manual Alternative (If Script Doesn't Work)

Step-by-Step

# 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

# 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'"

# Fix:
python3 -m ensurepip --upgrade

"error: externally-managed-environment"

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

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

"ERROR: Could not build wheels for psycopg2"

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

"Requirement already satisfied" but import fails

# 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)

# 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

# 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

# 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+