Environment Setup Guide

Development Environment Configuration

Port Conventions (Strictly Follow)

Database Connections

# Test/Development Environment
Local Port: 5433 → Remote Port: 5432
ssh -L 5433:localhost:5432 user@test-server

# Production Environment
Local Port: 5434 → Remote Port: 5432
ssh -L 5434:localhost:5432 user@prod-server

Application Ports

# Development Services
Django Dev Server: 8000
React Dev Server: 3000
MkDocs Server: 8001
Storybook: 6006

# Production Services
Django (Gunicorn): 8000
Nginx: 80, 443
Redis: 6379
Celery Flower: 5555

Environment Variables Template

Django Backend (.env)

# Django Configuration
DEBUG=True
SECRET_KEY=your-secret-key-here
DJANGO_SETTINGS_MODULE=project.settings.development

# Database
DATABASE_URL=postgresql://user:password@localhost:5433/db_name
DB_NAME=project_dev
DB_USER=postgres
DB_PASSWORD=password
DB_HOST=localhost
DB_PORT=5433

# Redis/Celery
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# DigitalOcean Spaces
USE_SPACES=FALSE
AWS_ACCESS_KEY_ID=your_spaces_key
AWS_SECRET_ACCESS_KEY=your_spaces_secret
AWS_STORAGE_BUCKET_NAME=your_bucket

# Sentry
SENTRY_DSN=https://[email protected]/project-id
ENVIRONMENT=development

# Email (Development)
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

React Frontend (.env.local)

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000/api
NEXT_PUBLIC_ENVIRONMENT=development

# Authentication
NEXT_PUBLIC_JWT_SECRET=your-jwt-secret

# Analytics (Development)
NEXT_PUBLIC_GA_TRACKING_ID=
NEXT_PUBLIC_SENTRY_DSN=

# Feature Flags
NEXT_PUBLIC_ENABLE_DEBUG=true
NEXT_PUBLIC_ENABLE_MOCK_API=false

SSH Configuration

SSH Config File (~/.ssh/config)

# Test Environment
Host azmx-test
    HostName test.azmx.sa
    User deploy
    Port 22
    IdentityFile ~/.ssh/azmx_test_key
    LocalForward 5433 localhost:5432

# Production Environment
Host azmx-prod
    HostName prod.azmx.sa
    User deploy
    Port 22
    IdentityFile ~/.ssh/azmx_prod_key
    LocalForward 5434 localhost:5432

Quick Connect Commands

# Connect to test with port forwarding
ssh azmx-test

# Connect to production with port forwarding
ssh azmx-prod

# One-time port forwarding
ssh -L 5433:localhost:5432 [email protected]
ssh -L 5434:localhost:5432 [email protected]

Docker Configuration

Development Docker Compose

# docker-compose.dev.yml
version: '3.8'

services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: azmx_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports:
      - "5433:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  backend:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/azmx_dev
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - postgres
      - redis

volumes:
  postgres_data:

IDE Configuration

VS Code Settings (.vscode/settings.json)

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "eslint.workingDirectories": ["frontend"],
  "prettier.configPath": "frontend/.prettierrc",
  "typescript.preferences.importModuleSpecifier": "relative",
  "files.exclude": {
    "**/__pycache__": true,
    "**/node_modules": true,
    "**/.pytest_cache": true
  }
}

VS Code Extensions (.vscode/extensions.json)

{
  "recommendations": [
    "ms-python.python",
    "ms-python.black-formatter",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense",
    "ms-vscode.vscode-json",
    "mtxr.sqltools",
    "mtxr.sqltools-driver-pg"
  ]
}

Git Configuration

Global Git Configuration

# Set up user information
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Set up useful aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'

# Set up default branch
git config --global init.defaultBranch main

# Set up pull strategy
git config --global pull.rebase true

Project-specific Git Hooks

#!/bin/bash
# .git/hooks/pre-commit

# Run linting and tests before commit
echo "Running pre-commit checks..."

# Python checks
if [ -f "requirements.txt" ]; then
    echo "Running Python linting..."
    black --check .
    flake8 .
fi

# JavaScript/TypeScript checks
if [ -f "package.json" ]; then
    echo "Running frontend linting..."
    npm run lint
    npm run type-check
fi

echo "Pre-commit checks completed!"

Database Setup

PostgreSQL Configuration

-- Create development database
CREATE DATABASE azmx_dev;
CREATE USER azmx_user WITH PASSWORD 'development_password';
GRANT ALL PRIVILEGES ON DATABASE azmx_dev TO azmx_user;

-- Create test database
CREATE DATABASE azmx_test;
GRANT ALL PRIVILEGES ON DATABASE azmx_test TO azmx_user;

Database Connection Testing

# Test development connection
psql "host=localhost port=5433 user=azmx_user dbname=azmx_dev"

# Test production connection (through tunnel)
psql "host=localhost port=5434 user=azmx_user dbname=azmx_prod"

# Connection with SSL
psql "sslmode=require host=localhost port=5433 user=azmx_user dbname=azmx_dev"

Development Tools Setup

Python Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Deactivate
deactivate

Node.js Environment

# Install Node.js (using nvm)
nvm install node
nvm use node

# Install dependencies
npm install

# Install global tools
npm install -g @storybook/cli
npm install -g typescript
npm install -g eslint

Environment Validation Script

validation.sh

#!/bin/bash
echo "🔍 Validating AzmX Development Environment..."

# Check Python
if command -v python3 &> /dev/null; then
    echo "✅ Python3 installed: $(python3 --version)"
else
    echo "❌ Python3 not found"
fi

# Check Node.js
if command -v node &> /dev/null; then
    echo "✅ Node.js installed: $(node --version)"
else
    echo "❌ Node.js not found"
fi

# Check PostgreSQL client
if command -v psql &> /dev/null; then
    echo "✅ PostgreSQL client installed: $(psql --version)"
else
    echo "❌ PostgreSQL client not found"
fi

# Check Git
if command -v git &> /dev/null; then
    echo "✅ Git installed: $(git --version)"
else
    echo "❌ Git not found"
fi

# Check Docker
if command -v docker &> /dev/null; then
    echo "✅ Docker installed: $(docker --version)"
else
    echo "❌ Docker not found"
fi

# Test database connections
echo "🔍 Testing database connections..."

# Test development database
if nc -z localhost 5433; then
    echo "✅ Development database port (5433) is accessible"
else
    echo "❌ Development database port (5433) not accessible"
fi

# Test production database
if nc -z localhost 5434; then
    echo "✅ Production database port (5434) is accessible"
else
    echo "❌ Production database port (5434) not accessible"
fi

echo "🎉 Environment validation completed!"

[This setup guide ensures consistent development environments across the team]