Add development tools and documentation for environment management

**Development Script:** - Add run_dev.sh for clean development server startup - Automatically unsets DATABASE_URL to prevent conflicts - Shows database configuration before starting server - Provides clear development workflow **Development Guide:** - Comprehensive development documentation - Environment variable troubleshooting - Database configuration options - Common issues and solutions - Development workflow best practices **Fixes Environment Variable Conflicts:** - Documents DATABASE_URL interference issue - Provides permanent and temporary solutions - Clear instructions for different development scenarios - Troubleshooting guide for connection errors **Developer Experience:** - One-command development startup: ./run_dev.sh - Clear documentation for all development scenarios - Troubleshooting guide for common issues - Environment management best practices 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-18 07:52:58 +00:00 · 2025-07-12 10:22:13 +05:30 · 2025-07-12 10:22:13 +05:30 · 056db5215b
commit 056db5215b
parent ed51bb95ee
2 changed files with 257 additions and 0 deletions
--- a/docs/DEVELOPMENT_GUIDE.md
+++ b/docs/DEVELOPMENT_GUIDE.md
@ -0,0 +1,229 @@
+# Development Guide
+
+## Quick Start
+
+### Option 1: Use the Development Script (Recommended)
+```bash
+./run_dev.sh
+```
+
+### Option 2: Manual Startup
+```bash
+# Clear any interfering environment variables
+unset DATABASE_URL
+
+# Activate virtual environment
+source venv/bin/activate
+
+# Start server
+python manage.py runserver
+```
+
+## Common Issues
+
+### Issue: "Connection refused" Error with PostgreSQL
+**Cause:** You have `DATABASE_URL` set as an environment variable pointing to PostgreSQL.
+
+**Solution:**
+```bash
+# Check if DATABASE_URL is set
+echo $DATABASE_URL
+
+# Temporarily unset it
+unset DATABASE_URL
+
+# Start server
+python manage.py runserver
+```
+
+**Permanent Fix:**
+If `DATABASE_URL` keeps getting set, check these files:
+- `~/.bashrc`
+- `~/.bash_profile` 
+- `~/.profile`
+- `~/.zshrc`
+- `~/.env` (global)
+
+Remove any lines containing `DATABASE_URL=` unless you specifically need them.
+
+### Issue: Database Tables Don't Exist
+```bash
+# Run migrations
+python manage.py migrate
+
+# Create admin user and populate data
+python manage.py populate_agents --create-admin
+```
+
+### Issue: Admin Login Not Working
+```bash
+# Check if admin user exists
+python manage.py backup_users --action info
+
+# Create admin user
+python manage.py create_user admin@example.com password123 --superuser
+```
+
+## Database Configuration
+
+### Local Development (Default)
+- **Engine:** SQLite
+- **Location:** `db.sqlite3`
+- **Setup:** None required
+
+### Local Development with PostgreSQL (Optional)
+1. **Set up PostgreSQL:**
+   ```bash
+   # Using Docker (easiest)
+   docker run --name netcop-postgres \\
+     -e POSTGRES_DB=netcop_hub \\
+     -e POSTGRES_USER=netcop_user \\
+     -e POSTGRES_PASSWORD=netcop_pass \\
+     -p 5432:5432 -d postgres:15
+   ```
+
+2. **Enable in .env:**
+   ```env
+   USE_POSTGRESQL=True
+   ```
+
+3. **Run migrations:**
+   ```bash
+   python manage.py migrate
+   python manage.py populate_agents --create-admin
+   ```
+
+### Railway Production
+- **Engine:** PostgreSQL (automatic)
+- **Configuration:** Via Railway's `DATABASE_URL`
+- **Setup:** None required
+
+## Environment Variables
+
+### Required for Development
+```env
+SECRET_KEY=your-secret-key-here
+DEBUG=True
+ALLOWED_HOSTS=localhost,127.0.0.1
+CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
+```
+
+### Optional for Development
+```env
+# Force PostgreSQL (requires PostgreSQL setup)
+USE_POSTGRESQL=True
+
+# Or specify exact database URL
+DATABASE_URL=postgresql://netcop_user:netcop_pass@localhost:5432/netcop_hub
+
+# API Keys (for full functionality)
+OPENWEATHER_API_KEY=your-key-here
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+## Development Workflow
+
+### Daily Development
+```bash
+# Start development server
+./run_dev.sh
+
+# In another terminal - run commands
+source venv/bin/activate
+python manage.py check_db          # Check database status
+python manage.py makemigrations    # Create migrations
+python manage.py migrate           # Apply migrations
+```
+
+### Testing Changes
+```bash
+# Check for issues
+python manage.py check
+
+# Test migrations
+python manage.py migrate --plan
+
+# Create test data
+python manage.py populate_agents --create-admin
+```
+
+### Debugging
+```bash
+# Check database configuration
+python manage.py check_db
+
+# Check migration status
+python manage.py showmigrations
+
+# Django shell
+python manage.py shell
+```
+
+## File Structure
+
+```
+netcop_django/
+├── run_dev.sh              # Development startup script
+├── manage.py               # Django management
+├── requirements.txt        # Python dependencies
+├── .env                   # Local environment variables
+├── db.sqlite3             # SQLite database (local)
+├── docs/                  # Documentation
+├── static/                # Static files
+├── templates/             # Global templates
+├── netcop_hub/            # Django project settings
+├── core/                  # Main app (homepage, marketplace)
+├── authentication/       # User management
+├── wallet/               # Payment system
+├── agent_base/           # Agent framework
+├── weather_reporter/     # Weather agent
+├── data_analyzer/        # Data analysis agent
+├── job_posting_generator/ # Job posting agent
+└── social_ads_generator/ # Social ads agent
+```
+
+## Useful Commands
+
+```bash
+# Development
+./run_dev.sh                                    # Start dev server
+python manage.py check_db                       # Check database
+python manage.py migrate                        # Run migrations
+python manage.py populate_agents --create-admin # Setup data
+
+# User Management
+python manage.py create_user email@example.com password123 --superuser
+python manage.py backup_users --action info
+
+# Database Management
+python manage.py reset_database --action full --confirm
+python manage.py fix_migrations --app data_analyzer
+
+# Debugging
+python manage.py check                          # System check
+python manage.py showmigrations                 # Migration status
+python manage.py shell                          # Django shell
+```
+
+## Troubleshooting
+
+### Server Won't Start
+1. Check if `DATABASE_URL` is set: `echo $DATABASE_URL`
+2. Unset it: `unset DATABASE_URL` 
+3. Use the development script: `./run_dev.sh`
+
+### Database Issues
+1. Check configuration: `python manage.py check_db`
+2. Run migrations: `python manage.py migrate`
+3. Reset if needed: `python manage.py reset_database --action full --confirm`
+
+### Import Errors
+1. Activate virtual environment: `source venv/bin/activate`
+2. Install requirements: `pip install -r requirements.txt`
+
+### Permission Errors
+1. Make script executable: `chmod +x run_dev.sh`
+2. Check file permissions: `ls -la`
+
+Happy coding! 🎉
--- a/run_dev.sh
+++ b/run_dev.sh
@ -0,0 +1,28 @@
+#!/bin/bash
+# Development server startup script
+# Ensures clean environment for Django development
+
+echo "🚀 Starting Django Development Server"
+echo "======================================"
+
+# Clear any DATABASE_URL that might interfere with local development
+unset DATABASE_URL
+
+# Activate virtual environment
+echo "📦 Activating virtual environment..."
+source venv/bin/activate
+
+# Check database configuration
+echo "🔍 Checking database configuration..."
+python manage.py check_db
+
+echo ""
+echo "🌐 Starting Django server..."
+echo "Visit: http://localhost:8000"
+echo "Admin: http://localhost:8000/admin"
+echo ""
+echo "Press Ctrl+C to stop the server"
+echo "======================================"
+
+# Start the development server
+python manage.py runserver