giglez/docs/WEBAPP_STARTUP_GUIDE.md

GigLez Web App Startup Guide

Problem: Errors When Starting Web App

When running python3 src/api/main.py, you encountered multiple errors. Here's what was causing them and how to fix it.

---

Root Causes

1. Import Path Conflict ❌

Error:

ImportError: cannot import name 'settings' from 'config.settings'

Cause: Python was importing from the system config package instead of the local config/settings.py

Fix: Added sys.path.insert(0, ...) to prioritize local imports

2. Database Connection Requirement ❌

Error: Application hangs/fails during startup trying to connect to PostgreSQL

Cause: The main API (src/api/main.py) requires:

• PostgreSQL database connection
• PostGIS extension
• Database initialization

The startup lifecycle includes:

# Test database connection
db_config = get_db_config()
if not db_config.test_connection():
    raise RuntimeError("Database connection failed")

if not db_config.test_postgis():
    raise RuntimeError("PostGIS extension not available")

This blocks startup if PostgreSQL isn't configured.

---

Solutions

Option 1: Simplified Web Server ✅ (Recommended for Testing)

File: src/api/main_simple.py

Features:

• ✅ Serves web interface (HTML, CSS, JS)
• ✅ No database requirement
• ✅ Mock API endpoints (empty data)
• ✅ Perfect for testing UI/UX

Start command:

python3 src/api/main_simple.py

Access:

Web Interface: http://localhost:8000
API Docs:      http://localhost:8000/docs
Health Check:  http://localhost:8000/health

Limitations:

• ❌ Cannot upload files
• ❌ No database queries
• ❌ No device matching
• ✅ Map, search, and stats work (with empty data)

Option 2: Full API Server (Requires Database Setup)

File: src/api/main.py

Requirements:

1. PostgreSQL installed and running
2. Database and user created
3. PostGIS extension installed

Setup steps:

# Run database setup script
./scripts/quick_db_setup.sh

# OR manually:
sudo -u postgres psql
CREATE USER giglez_user WITH PASSWORD 'giglez_secure_password_2026';
CREATE DATABASE giglez OWNER giglez_user;
\c giglez
CREATE EXTENSION postgis;

Start command:

python3 src/api/main.py

---

Current Status

✅ Working Now (Simplified Server)

# Server is running
python3 src/api/main_simple.py

# Output:
# INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
# INFO:     Application startup complete.

Test it:

# Health check
curl http://localhost:8000/health
# Response: {"status":"healthy","database":"not_connected","mode":"simple"}

# Web interface
# Open browser: http://localhost:8000

---

Web Interface Features (Working Now)

✅ Available

• Interactive map (Leaflet.js)
• Navigation between sections
• Responsive design
• Statistics dashboard (shows 0s without data)
• Search interface (no results without data)
• Upload form (UI only, backend disabled)

⏳ Requires Full Server + Database

• File uploads
• Device matching
• Database queries
• Real capture data on map

---

Startup Scripts

Quick Start (Simplified)

Created: Simple startup for testing

python3 src/api/main_simple.py

Full Start (Requires DB)

# Setup database first
./scripts/quick_db_setup.sh

# Then start full server
python3 src/api/main.py

---

Error Debugging

If you see: "ImportError: cannot import name 'settings'"

Fix: Already fixed in src/api/main.py with:

import sys
sys.path.insert(0, str(Path(__file__).parent.parent.parent))

If you see: "Database connection failed"

Options:

1. Use simplified server: python3 src/api/main_simple.py
2. Setup PostgreSQL: ./scripts/quick_db_setup.sh

If you see: "Address already in use"

Cause: Port 8000 already in use

Fix:

# Find process
lsof -i :8000

# Kill it
kill -9 <PID>

# Or use different port
python3 src/api/main_simple.py  # Edit file to change port

---

Testing the Web Interface

1. Start Server

cd /path/to/giglez
python3 src/api/main_simple.py

2. Open Browser

http://localhost:8000

3. Test Features

Map View:

• ✅ Map loads
• ✅ Controls visible
• ⏹️ No markers (no data)

Upload View:

• ✅ Drag-drop zone visible
• ✅ GPS input fields work
• ⏹️ Upload disabled (no backend)

Search View:

• ✅ Search form visible
• ✅ Filters functional
• ⏹️ No results (no data)

Statistics View:

• ✅ Cards display (showing 0s)
• ✅ Charts render (empty)

---

Next Steps

For UI/UX Testing (Now)

1. ✅ Use src/api/main_simple.py
2. ✅ Test navigation
3. ✅ Test responsive design
4. ✅ Test JavaScript functionality
5. ✅ Verify layout and styling

For Full Functionality (Later)

1. Setup PostgreSQL database
2. Import signature data
3. Switch to src/api/main.py
4. Test uploads and matching

---

File Comparison

src/api/main.py (Full API)

Lines: 263 Features: Complete API with all endpoints Requires: PostgreSQL + PostGIS Use case: Production deployment

src/api/main_simple.py (Simplified)

Lines: 141 Features: Web interface + mock endpoints Requires: Nothing Use case: Testing UI/UX

---

Port Information

Default Port: 8000

Check if running:

curl http://localhost:8000/health

View in browser:

http://localhost:8000

API docs:

http://localhost:8000/docs

---

Summary

Problem: Main API requires PostgreSQL database Solution: Created simplified version for testing Status: ✅ Web interface accessible and functional Command: python3 src/api/main_simple.py URL: http://localhost:8000

The web interface is now running successfully! 🎉