agent_tracker/README_DEV.md

Local Development Setup

This guide explains how to set up AgentHub for local development without MSAL authentication.

Prerequisites

• Python 3.8+
• MongoDB (running locally or accessible)
• Git

Local Development Setup

1. Copy Environment Configuration

Copy the local development environment file:

cp .env.local .env

This sets up the following configuration:

• DISABLE_MSAL=true - Disables Microsoft authentication
• BASE_PATH="" - Sets base path to root for local development
• Commented out Azure AD configuration (not needed for local development)

2. Install Dependencies

# Create virtual environment (if not already created)
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Start MongoDB

Make sure MongoDB is running locally:

# Using homebrew on macOS:
brew services start mongodb-community

# Using systemd on Linux:
sudo systemctl start mongod

# Or run manually:
mongod --dbpath /path/to/your/db

4. Run the Application

# Make sure virtual environment is activated
source venv/bin/activate

# Start the application
uvicorn main:app --reload --host 127.0.0.1 --port 8000

The application will be available at: http://localhost:8000

5. Create Initial Admin User

When running locally, you'll only have access to local authentication. To create an admin user:

1. Visit http://localhost:8000/register
2. Register with email: admin@local.dev and a password
3. Run the admin promotion script:

source venv/bin/activate
python make_admin.py admin@local.dev

Development vs Production Configuration

Local Development (.env)

DISABLE_MSAL=true
BASE_PATH=
# No MSAL configuration needed

Production Server (server's .env)

DISABLE_MSAL=false
BASE_PATH=/agent_tracker
AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef
AZURE_AUTHORITY=https://login.microsoftonline.com/e519c2e6-bc6d-4fdf-8d9c-923c2f002385
AZURE_REDIRECT_URI=https://ai-sandbox.oliver.solutions/agent_tracker/auth/azure/callback

Key Differences

Local Development

• URL: http://localhost:8000
• Base Path: Root path (/)
• Authentication: Local login only
• Microsoft Button: Hidden (not displayed)

Production Server

• URL: https://ai-sandbox.oliver.solutions/agent_tracker
• Base Path: Sub-path (/agent_tracker)
• Authentication: Microsoft primary + local fallback
• Microsoft Button: Displayed prominently

Features Available in Local Mode

✅ Available:

• Local user registration and login
• Agent management (create, edit, delete)
• User management
• Search functionality
• Admin dashboard
• All core functionality

❌ Not Available:

• Microsoft/Azure AD authentication
• Single sign-on (SSO)

Troubleshooting

Application won't start

• Check MongoDB is running
• Verify virtual environment is activated
• Check all dependencies are installed: pip install -r requirements.txt

Template/Static file issues

• Ensure BASE_PATH="" in local .env file
• Clear browser cache
• Check console for 404 errors

Database issues

• Verify MongoDB URI in .env: MONGODB_URI=mongodb://localhost:27017
• Check database name: MONGODB_DBNAME=agenthub_db

Switching Between Environments

To switch from local to production configuration:

# For local development
cp .env.local .env

# For production (manual editing required)
# Edit .env to set DISABLE_MSAL=false and proper BASE_PATH

File Structure

• .env - Current environment configuration
• .env.local - Template for local development
• config.py - Configuration management utilities
• msal_auth.py - MSAL authentication (disabled in local mode)
• main.py - Main application with conditional MSAL routes