Complete Setup Guide - AI Trip Data Verbalization System

This guide covers three scenarios: Initial Setup, Development Workflow, and Running Again.

📋 Table of Contents

Initial Setup (First Time)
Development Workflow
Running Again (Subsequent Sessions)
Troubleshooting

🆕 Initial Setup (First Time)

Follow these steps when setting up the project for the first time.

Step 1: Install Prerequisites

1.1 Install PostgreSQL with PostGIS

Windows:

Download PostgreSQL from https://www.postgresql.org/download/windows/
Run the installer (recommended version: 15 or 16)
During installation:
- Set password for postgres user (remember this!)
- Port: 5432 (default)
- Install Stack Builder when prompted
In Stack Builder:
- Select "Spatial Extensions"
- Install PostGIS 3.x

Docker Alternative:

docker run --name postgis -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgis/postgis:15-3.3

1.2 Install MongoDB

Windows:

Download from https://www.mongodb.com/try/download/community
Run the installer
Choose "Complete" installation
Install as Windows Service (port 27017)

Docker Alternative:

docker run --name mongodb -p 27017:27017 -d mongo:latest

Cloud Alternative (MongoDB Atlas):

Create free account at https://www.mongodb.com/cloud/atlas
Create free cluster
Get connection string

1.3 Verify Installations

# Check PostgreSQL
psql --version

# Check MongoDB
mongosh --version

# Check Python
python --version
# Should be 3.9 or higher

Step 2: Create and Configure Database

2.1 Create PostgreSQL Database

# Connect to PostgreSQL
psql -U postgres

# Inside psql prompt:
CREATE DATABASE trip_verbalization;
\c trip_verbalization
CREATE EXTENSION postgis;
\q

Verify PostGIS:

psql -U postgres -d trip_verbalization -c "SELECT PostGIS_version();"

2.2 Test MongoDB Connection

# Using mongosh
mongosh
> use trip_verbalization
> db.test.insertOne({test: "connection"})
> db.test.find()
> exit

Step 3: Setup Python Environment

# Navigate to project directory
cd "d:\5th Sem\dbms"

# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate

# Upgrade pip (optional but recommended)
python -m pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Install async PostgreSQL driver
pip install asyncpg

Step 4: Configure Environment Variables

4.1 Create .env File

copy .env.example .env
notepad .env

4.2 Generate JWT Secret Key

python -c "import secrets; print(secrets.token_hex(32))"

Copy the output.

4.3 Edit .env File

Update the following in .env:

# PostgreSQL - Update password if different
DATABASE_URL=postgresql://postgres:your_postgres_password@localhost:5432/trip_verbalization

# MongoDB - Local installation
MONGODB_URL=mongodb://localhost:27017/trip_verbalization

# MongoDB Atlas alternative
# MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/trip_verbalization

# JWT Secret - Paste the generated key here
JWT_SECRET_KEY=paste_your_generated_secret_here
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# External APIs (optional, leave empty for now)
GEOCODING_API_KEY=
LLM_API_KEY=

# Application Settings
APP_NAME=AI Trip Data Verbalization System
APP_VERSION=1.0.0
DEBUG=True
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000

Save and close the file.

Step 5: Initialize Database

# Make sure virtual environment is activated
# You should see (venv) in your prompt

python init_db.py

Expected Output:

Initializing database...
Creating PostGIS extension...
Creating tables...
Database initialized successfully!

Creating default admin user...
Admin user created successfully!
  Username: admin
  Password: admin123
  ⚠️  Please change the password after first login!

Step 6: Run the Application

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Expected Output:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
Starting AI Trip Data Verbalization System v1.0.0
Debug mode: True
Initializing database...
Database initialized successfully
INFO:     Application startup complete.

Step 7: Access and Test

Open API Documentation:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
Test the API:
- Click "Authorize" button in Swagger UI
- Login with:
  - Username: admin
  - Password: admin123
- Try creating a trip, searching trips, etc.

🔧 Development Workflow

Creating New Features

1. Add New Database Models

Edit app/models.py:

class NewModel(Base):
    __tablename__ = "new_table"
    id = Column(Integer, primary_key=True)
    # ... add fields

2. Create Validation Schemas

Edit app/schemas.py:

class NewModelCreate(BaseModel):
    field: str
    # ... add validators

3. Create New Router

Create app/routers/new_feature.py:

from fastapi import APIRouter, Depends
from ..auth import get_current_active_user

router = APIRouter(prefix="/new", tags=["New Feature"])

@router.post("/")
async def create_item(...):
    pass

4. Register Router

Edit app/main.py:

from .routers import auth, trips, config, feedback, new_feature

app.include_router(new_feature.router)

5. Update Database Schema

# Drop and recreate (WARNING: Deletes all data!)
python init_db.py drop
python init_db.py

# Or use Alembic for migrations (recommended for production)

6. Test Changes

# Restart the server (Ctrl+C, then)
uvicorn app.main:app --reload

Making Code Changes

The development server (--reload flag) automatically restarts when you save files:

Edit files in app/ directory
Save the file
Server automatically reloads
Test changes in browser at http://localhost:8000/docs

Files to edit:

Models: app/models.py (database tables)
Schemas: app/schemas.py (validation)
Auth: app/auth.py (authentication logic)
Routes: app/routers/*.py (API endpoints)
Config: app/config.py (settings)

Adding New Dependencies

# Activate virtual environment
venv\Scripts\activate

# Install new package
pip install package-name

# Update requirements.txt
pip freeze > requirements.txt

🔄 Running Again (Subsequent Sessions)

Use these steps every time you want to run the application after initial setup.

Quick Start (Every Time)

# 1. Navigate to project
cd "d:\5th Sem\dbms"

# 2. Activate virtual environment
venv\Scripts\activate

# 3. Start the application
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

That's it! Open http://localhost:8000/docs in your browser.

If Database Services Aren't Running

Start PostgreSQL

Windows Service:

# Check status
Get-Service postgresql*

# Start if needed
Start-Service postgresql-x64-15  # Adjust version number

Docker:

docker start postgis

Start MongoDB

Windows Service:

# Check status
Get-Service MongoDB

# Start if needed
Start-Service MongoDB

Docker:

docker start mongodb

After Pulling Code Changes

If you've pulled updates from Git:

# 1. Activate environment
venv\Scripts\activate

# 2. Update dependencies
pip install -r requirements.txt

# 3. Check for database changes
# If models.py changed, you may need to:
python init_db.py

# 4. Run application
uvicorn app.main:app --reload

Running Tests (Future)

# When tests are implemented
pytest

# With coverage
pytest --cov=app tests/

🐛 Troubleshooting

Issue: "ModuleNotFoundError"

Solution:

# Ensure virtual environment is activated
venv\Scripts\activate

# Reinstall dependencies
pip install -r requirements.txt

Issue: "Connection to database failed"

PostgreSQL:

# Check if running
psql -U postgres -d trip_verbalization

# Verify .env has correct credentials
notepad .env

# Test connection
psql -U postgres -d trip_verbalization -c "SELECT 1;"

MongoDB:

# Check if running
mongosh

# Restart service
net stop MongoDB
net start MongoDB

Issue: "PostGIS extension not found"

Solution:

psql -U postgres -d trip_verbalization

Inside psql:

CREATE EXTENSION IF NOT EXISTS postgis;
\dx  -- List installed extensions
\q

Issue: "Port 8000 already in use"

Solution:

# Find process using port 8000
netstat -ano | findstr :8000

# Kill the process (replace PID with actual process ID)
taskkill /PID <PID> /F

# Or use a different port
uvicorn app.main:app --reload --port 8001

Issue: "asyncpg module not found"

Solution:

pip install asyncpg

Issue: "JWT decode error"

Solution:

Logout from Swagger UI

Generate new JWT secret:

python -c "import secrets; print(secrets.token_hex(32))"

Update .env with new secret
Restart application
Login again

Issue: "Database tables don't exist"

Solution:

# Reinitialize database
python init_db.py

📝 Quick Reference Commands

Daily Development

# Start development session
cd "d:\5th Sem\dbms"
venv\Scripts\activate
uvicorn app.main:app --reload

# Stop server: Ctrl+C
# Deactivate virtual environment: deactivate

Database Management

# Connect to PostgreSQL
psql -U postgres -d trip_verbalization

# Common SQL commands
\dt              # List tables
\d table_name    # Describe table
SELECT * FROM users LIMIT 5;

# MongoDB
mongosh
> use trip_verbalization
> show collections
> db.collection_name.find()

Reset Database (WARNING: Deletes all data!)

python init_db.py drop
python init_db.py

🎯 Checklist for Each Scenario

✅ Initial Setup Checklist

✅ Daily Development Checklist

Navigate to project directory
Activate virtual environment
PostgreSQL running
MongoDB running
Start application (uvicorn app.main:app --reload)
Access http://localhost:8000/docs

✅ After Pulling Changes Checklist

Pull latest code
Activate virtual environment
Update dependencies (pip install -r requirements.txt)
Check for model changes (reinit db if needed)
Run application

🚀 Next Steps

Once your development environment is running:

Change admin password via Swagger UI
Create test users with different roles
Test all API endpoints interactively
Integrate LLM for trip verbalization
Add geocoding service for address resolution
Build frontend application

For detailed API documentation, see: README.md
For implementation details, see: walkthrough.md

FilesExpand file tree

SETUP_GUIDE.md

Latest commit

History

SETUP_GUIDE.md

File metadata and controls

Complete Setup Guide - AI Trip Data Verbalization System

📋 Table of Contents

🆕 Initial Setup (First Time)

Step 1: Install Prerequisites

1.1 Install PostgreSQL with PostGIS

1.2 Install MongoDB

1.3 Verify Installations

Step 2: Create and Configure Database

2.1 Create PostgreSQL Database

2.2 Test MongoDB Connection

Step 3: Setup Python Environment

Step 4: Configure Environment Variables

4.1 Create .env File

4.2 Generate JWT Secret Key

4.3 Edit .env File

Step 5: Initialize Database

Step 6: Run the Application

Step 7: Access and Test

🔧 Development Workflow

Creating New Features

1. Add New Database Models

2. Create Validation Schemas

3. Create New Router

4. Register Router

5. Update Database Schema

6. Test Changes

Making Code Changes

Adding New Dependencies

🔄 Running Again (Subsequent Sessions)

Quick Start (Every Time)

If Database Services Aren't Running

Start PostgreSQL

Start MongoDB

After Pulling Code Changes

Running Tests (Future)

🐛 Troubleshooting

Issue: "ModuleNotFoundError"

Issue: "Connection to database failed"

Issue: "PostGIS extension not found"

Issue: "Port 8000 already in use"

Issue: "asyncpg module not found"

Issue: "JWT decode error"

Issue: "Database tables don't exist"

📝 Quick Reference Commands

Daily Development

Database Management

Reset Database (WARNING: Deletes all data!)

🎯 Checklist for Each Scenario

✅ Initial Setup Checklist

✅ Daily Development Checklist

✅ After Pulling Changes Checklist

🚀 Next Steps