add mintlify intro docs

developer-docs/contributing/project-setup/environment-variables.mdx

@@ -0,0 +1,658 @@
+---
+title: Environment Variables for Development
+description: Complete guide to environment variables for Chatwoot development and testing
+sidebarTitle: Environment Variables
+---
+
+# Environment Variables for Development
+
+This guide covers environment variables specifically for development and testing environments. For production environment variables, see the [Self-hosted Environment Variables](../../self-hosted/configuration/environment-variables) guide.
+
+## Development Environment Setup
+
+### Basic Development Configuration
+
+Create your `.env` file from the example:
+
+```bash
+cp .env.example .env
+```
+
+### Essential Development Variables
+
+```bash
+# Rails Environment
+RAILS_ENV=development
+NODE_ENV=development
+
+# Application Configuration
+FRONTEND_URL=http://localhost:3000
+FORCE_SSL=false
+SECRET_KEY_BASE=your-secret-key-here
+
+# Database Configuration
+DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
+REDIS_URL=redis://localhost:6379/0
+
+# Development Features
+ENABLE_DEVELOPMENT_FEATURES=true
+RAILS_LOG_LEVEL=debug
+LOG_LEVEL=debug
+```
+
+## Database Configuration
+
+### PostgreSQL Settings
+
+```bash
+# Primary database connection
+DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_development
+
+# Alternative format (individual variables)
+DB_HOST=localhost
+DB_PORT=5432
+DB_USERNAME=chatwoot
+DB_PASSWORD=password
+DB_NAME=chatwoot_development
+
+# Test database
+TEST_DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_test
+```
+
+### Redis Configuration
+
+```bash
+# Redis connection for development
+REDIS_URL=redis://localhost:6379/0
+
+# Redis with authentication
+REDIS_URL=redis://:password@localhost:6379/0
+
+# Redis Sentinel (for advanced setups)
+REDIS_SENTINELS=localhost:26379
+REDIS_SENTINEL_MASTER_NAME=mymaster
+
+# Sidekiq Redis (can be separate)
+SIDEKIQ_REDIS_URL=redis://localhost:6379/1
+```
+
+## Email Configuration for Development
+
+### Local Email Testing
+
+```bash
+# MailHog configuration (recommended for development)
+MAILER_SENDER_EMAIL=dev@chatwoot.local
+SMTP_ADDRESS=localhost
+SMTP_PORT=1025
+SMTP_DOMAIN=chatwoot.local
+SMTP_ENABLE_STARTTLS_AUTO=false
+SMTP_TLS=false
+
+# Alternative: Letter Opener (emails open in browser)
+LETTER_OPENER=true
+```
+
+### Gmail SMTP (for testing real emails)
+
+```bash
+MAILER_SENDER_EMAIL=your-email@gmail.com
+SMTP_ADDRESS=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+SMTP_DOMAIN=gmail.com
+SMTP_ENABLE_STARTTLS_AUTO=true
+SMTP_TLS=true
+```
+
+### Mailtrap (for testing)
+
+```bash
+MAILER_SENDER_EMAIL=dev@chatwoot.local
+SMTP_ADDRESS=smtp.mailtrap.io
+SMTP_PORT=2525
+SMTP_USERNAME=your-mailtrap-username
+SMTP_PASSWORD=your-mailtrap-password
+SMTP_DOMAIN=chatwoot.local
+```
+
+## File Storage Configuration
+
+### Local Storage (Default for Development)
+
+```bash
+ACTIVE_STORAGE_SERVICE=local
+```
+
+### AWS S3 for Development
+
+```bash
+ACTIVE_STORAGE_SERVICE=amazon
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_REGION=us-east-1
+AWS_BUCKET_NAME=chatwoot-dev-bucket
+```
+
+### Google Cloud Storage
+
+```bash
+ACTIVE_STORAGE_SERVICE=google
+GCS_PROJECT_ID=your-project-id
+GCS_CREDENTIALS=path/to/credentials.json
+GCS_BUCKET=chatwoot-dev-bucket
+```
+
+## Development Features
+
+### Debug and Logging
+
+```bash
+# Enable development features
+ENABLE_DEVELOPMENT_FEATURES=true
+
+# Logging levels
+RAILS_LOG_LEVEL=debug
+LOG_LEVEL=debug
+SIDEKIQ_LOG_LEVEL=debug
+
+# SQL query logging
+ACTIVE_RECORD_VERBOSE_QUERY_LOGS=true
+
+# Bullet gem for N+1 query detection
+BULLET_ENABLED=true
+```
+
+### Performance Monitoring
+
+```bash
+# Enable query analysis
+QUERY_ANALYSIS=true
+
+# Memory profiling
+MEMORY_PROFILER=true
+
+# Rack Mini Profiler
+RACK_MINI_PROFILER=true
+
+# Benchmark mode
+BENCHMARK_MODE=true
+```
+
+### Code Quality Tools
+
+```bash
+# RuboCop configuration
+RUBOCOP_PARALLEL=true
+
+# Coverage reporting
+COVERAGE=true
+SIMPLECOV_FORMATTER=html
+
+# Test environment
+RSPEC_RETRY_COUNT=3
+PARALLEL_TEST_PROCESSORS=4
+```
+
+## Testing Environment Variables
+
+### Test Database Configuration
+
+```bash
+# Test environment
+RAILS_ENV=test
+
+# Test database
+TEST_DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_test
+
+# Test Redis
+TEST_REDIS_URL=redis://localhost:6379/15
+
+# Disable external services in tests
+DISABLE_EXTERNAL_HTTP=true
+MOCK_EXTERNAL_SERVICES=true
+```
+
+### Test-Specific Settings
+
+```bash
+# Faster tests
+RAILS_ENV=test
+DISABLE_SPRING=true
+PARALLEL_WORKERS=4
+
+# Test coverage
+COVERAGE=true
+COVERAGE_REPORTS=true
+
+# Selenium/Capybara configuration
+SELENIUM_REMOTE_URL=http://localhost:4444/wd/hub
+CAPYBARA_SERVER_PORT=3001
+HEADLESS_CHROME=true
+
+# Factory Bot settings
+FACTORY_BOT_ALLOW_CLASS_LOOKUP=false
+```
+
+## Integration Testing
+
+### External Service Mocking
+
+```bash
+# Mock external APIs
+MOCK_FACEBOOK_API=true
+MOCK_TWITTER_API=true
+MOCK_WHATSAPP_API=true
+MOCK_TELEGRAM_API=true
+
+# Webhook testing
+WEBHOOK_TEST_URL=http://localhost:3000/webhooks/test
+NGROK_TUNNEL_URL=https://your-tunnel.ngrok.io
+```
+
+### API Testing
+
+```bash
+# API testing configuration
+API_TEST_TOKEN=test-token-123
+API_TEST_ACCOUNT_ID=1
+API_TEST_USER_ID=1
+
+# Rate limiting (disabled for tests)
+RATE_LIMITING_ENABLED=false
+```
+
+## Development Tools
+
+### Code Analysis
+
+```bash
+# Brakeman security scanner
+BRAKEMAN_ENABLED=true
+
+# Bundle audit
+BUNDLE_AUDIT_ENABLED=true
+
+# Reek code smell detector
+REEK_ENABLED=true
+
+# Rails Best Practices
+RAILS_BEST_PRACTICES_ENABLED=true
+```
+
+### Development Servers
+
+```bash
+# Webpack dev server
+WEBPACK_DEV_SERVER_HOST=localhost
+WEBPACK_DEV_SERVER_PORT=3035
+
+# Hot module replacement
+HMR_ENABLED=true
+
+# Live reload
+LIVE_RELOAD=true
+```
+
+## Third-Party Integrations (Development)
+
+### Social Media (Test Credentials)
+
+```bash
+# Facebook (use test app credentials)
+FB_APP_ID=your-test-app-id
+FB_APP_SECRET=your-test-app-secret
+FB_VERIFY_TOKEN=test-verify-token
+
+# Twitter (use test credentials)
+TWITTER_APP_ID=your-test-app-id
+TWITTER_CONSUMER_KEY=your-test-consumer-key
+TWITTER_CONSUMER_SECRET=your-test-consumer-secret
+
+# WhatsApp (use test credentials)
+WHATSAPP_VERIFY_TOKEN=test-verify-token
+```
+
+### Push Notifications (Development)
+
+```bash
+# FCM (use development project)
+FCM_SERVER_KEY=your-dev-server-key
+FCM_PROJECT_ID=your-dev-project-id
+
+# Vapid keys for web push
+VAPID_PUBLIC_KEY=your-dev-public-key
+VAPID_PRIVATE_KEY=your-dev-private-key
+```
+
+## Security Settings for Development
+
+### Authentication
+
+```bash
+# JWT settings
+JWT_SECRET_KEY=your-dev-jwt-secret
+JWT_EXPIRY=24h
+
+# Session configuration
+SESSION_TIMEOUT=1440
+SECURE_COOKIES=false
+
+# CORS settings (permissive for development)
+CORS_ORIGINS=http://localhost:3000,http://localhost:3001
+```
+
+### Development Security
+
+```bash
+# Disable security features for development
+FORCE_SSL=false
+SECURE_HEADERS=false
+CSP_ENABLED=false
+
+# Allow insecure connections
+ALLOW_HTTP=true
+SKIP_SSL_VERIFICATION=true
+```
+
+## Environment-Specific Configurations
+
+### Development Environment
+
+```bash
+# .env.development
+RAILS_ENV=development
+NODE_ENV=development
+CACHE_CLASSES=false
+EAGER_LOAD=false
+CONSIDER_ALL_REQUESTS_LOCAL=true
+ACTION_CONTROLLER_PERFORM_CACHING=false
+```
+
+### Test Environment
+
+```bash
+# .env.test
+RAILS_ENV=test
+NODE_ENV=test
+CACHE_CLASSES=true
+EAGER_LOAD=false
+PUBLIC_FILE_SERVER_ENABLED=true
+SHOW_EXCEPTIONS=false
+```
+
+### Staging Environment
+
+```bash
+# .env.staging
+RAILS_ENV=staging
+NODE_ENV=production
+FORCE_SSL=true
+LOG_LEVEL=info
+RAILS_SERVE_STATIC_FILES=true
+```
+
+## Docker Development
+
+### Docker Compose Variables
+
+```bash
+# Docker-specific configuration
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=chatwoot
+
+REDIS_HOST=redis
+REDIS_PORT=6379
+
+# Rails configuration for Docker
+RAILS_ENV=development
+RAILS_MAX_THREADS=5
+WEB_CONCURRENCY=2
+```
+
+### Development with Docker
+
+```bash
+# Use Docker services
+DATABASE_URL=postgresql://postgres:postgres@postgres:5432/chatwoot_development
+REDIS_URL=redis://redis:6379/0
+
+# File permissions (for volume mounts)
+DOCKER_USER_ID=1000
+DOCKER_GROUP_ID=1000
+```
+
+## IDE and Editor Configuration
+
+### VS Code Settings
+
+```bash
+# Ruby LSP configuration
+RUBY_LSP_ENABLED=true
+RUBY_LSP_EXPERIMENTAL_FEATURES=true
+
+# Solargraph configuration
+SOLARGRAPH_ENABLED=true
+```
+
+### RubyMine Settings
+
+```bash
+# RubyMine-specific settings
+RUBYMINE_PROJECT_ROOT=/path/to/chatwoot
+RUBYMINE_RUBY_VERSION=3.3.3
+```
+
+## Performance and Monitoring
+
+### Development Monitoring
+
+```bash
+# New Relic (development license)
+NEW_RELIC_LICENSE_KEY=your-dev-license-key
+NEW_RELIC_APP_NAME=Chatwoot Development
+
+# Sentry (development DSN)
+SENTRY_DSN=your-dev-sentry-dsn
+SENTRY_ENVIRONMENT=development
+
+# DataDog (development)
+DD_API_KEY=your-dev-datadog-key
+DD_ENV=development
+```
+
+### Memory and Performance
+
+```bash
+# Memory settings
+RUBY_GC_HEAP_INIT_SLOTS=10000
+RUBY_GC_HEAP_FREE_SLOTS=10000
+RUBY_GC_HEAP_GROWTH_FACTOR=1.1
+
+# Puma configuration
+PUMA_WORKERS=1
+PUMA_THREADS=5
+PUMA_PRELOAD_APP=false
+```
+
+## Common Development Scenarios
+
+### API Development
+
+```bash
+# API-specific settings
+API_RATE_LIMIT=1000
+API_RATE_LIMIT_WINDOW=3600
+API_PAGINATION_LIMIT=100
+
+# CORS for API development
+API_CORS_ORIGINS=http://localhost:3001,http://localhost:8080
+```
+
+### Widget Development
+
+```bash
+# Widget development
+WIDGET_BASE_URL=http://localhost:3000
+WIDGET_API_URL=http://localhost:3000/api/v1
+WIDGET_WS_URL=ws://localhost:3000/cable
+```
+
+### Mobile App Development
+
+```bash
+# Mobile API endpoints
+MOBILE_API_URL=http://localhost:3000/api/v1
+MOBILE_WS_URL=ws://localhost:3000/cable
+
+# Push notification testing
+MOBILE_PUSH_ENABLED=true
+```
+
+## Troubleshooting Environment Issues
+
+### Common Environment Problems
+
+<Accordion title="Database connection issues">
+**Problem**: `ActiveRecord::ConnectionNotEstablished`
+
+**Check these variables**:
+```bash
+DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_development
+DB_HOST=localhost
+DB_PORT=5432
+```
+
+**Verify connection**:
+```bash
+psql $DATABASE_URL -c "SELECT 1;"
+```
+</Accordion>
+
+<Accordion title="Redis connection issues">
+**Problem**: `Redis::CannotConnectError`
+
+**Check these variables**:
+```bash
+REDIS_URL=redis://localhost:6379/0
+```
+
+**Verify connection**:
+```bash
+redis-cli -u $REDIS_URL ping
+```
+</Accordion>
+
+<Accordion title="Email delivery issues">
+**Problem**: Emails not being sent in development
+
+**Check these variables**:
+```bash
+MAILER_SENDER_EMAIL=dev@chatwoot.local
+SMTP_ADDRESS=localhost
+SMTP_PORT=1025
+```
+
+**For MailHog**:
+```bash
+# Start MailHog
+mailhog
+
+# Check web interface at http://localhost:8025
+```
+</Accordion>
+
+<Accordion title="Asset compilation issues">
+**Problem**: `Webpacker::Manifest::MissingEntryError`
+
+**Check these variables**:
+```bash
+NODE_ENV=development
+RAILS_ENV=development
+```
+
+**Recompile assets**:
+```bash
+pnpm run dev
+# or
+bundle exec rails assets:precompile
+```
+</Accordion>
+
+### Environment Validation
+
+Create a script to validate your environment:
+
+```bash
+#!/bin/bash
+# validate_env.sh
+
+echo "Validating development environment..."
+
+# Check required variables
+required_vars=(
+  "RAILS_ENV"
+  "DATABASE_URL"
+  "REDIS_URL"
+  "SECRET_KEY_BASE"
+  "FRONTEND_URL"
+)
+
+for var in "${required_vars[@]}"; do
+  if [ -z "${!var}" ]; then
+    echo "❌ Missing required variable: $var"
+  else
+    echo "✅ $var is set"
+  fi
+done
+
+# Test database connection
+if bundle exec rails runner "ActiveRecord::Base.connection.execute('SELECT 1')" > /dev/null 2>&1; then
+  echo "✅ Database connection successful"
+else
+  echo "❌ Database connection failed"
+fi
+
+# Test Redis connection
+if bundle exec rails runner "Redis.new.ping" > /dev/null 2>&1; then
+  echo "✅ Redis connection successful"
+else
+  echo "❌ Redis connection failed"
+fi
+
+echo "Environment validation complete!"
+```
+
+## Best Practices
+
+### Environment File Management
+
+1. **Never commit `.env` files** to version control
+2. **Use `.env.example`** as a template for required variables
+3. **Document all variables** with comments
+4. **Use different `.env` files** for different environments
+5. **Validate environment** before starting development
+
+### Security Considerations
+
+1. **Use weak credentials** only in development
+2. **Never use production credentials** in development
+3. **Rotate test API keys** regularly
+4. **Use local services** when possible
+5. **Mock external services** in tests
+
+### Performance Tips
+
+1. **Use local Redis** for faster development
+2. **Enable query caching** in development
+3. **Use parallel testing** for faster test runs
+4. **Profile memory usage** regularly
+5. **Monitor database queries** for N+1 issues
+
+---
+
+This guide covers the essential environment variables for Chatwoot development. For production deployment, refer to the [Self-hosted Environment Variables](../../self-hosted/configuration/environment-variables) guide. 

developer-docs/contributing/project-setup/setup-guide.mdx

@@ -0,0 +1,589 @@
+---
+title: Project Setup Guide
+description: Complete guide to setting up Chatwoot for development and contribution
+sidebarTitle: Setup Guide
+---
+
+# Project Setup Guide
+
+This comprehensive guide will walk you through setting up Chatwoot for development, from initial repository setup to running your first successful build.
+
+## Prerequisites Check
+
+Before starting, ensure you have completed the [Local Development Setup](../environment-setup/local-development) guide and have all required dependencies installed.
+
+### Quick Prerequisites Verification
+
+```bash
+# Check Ruby version (should be 3.3.3)
+ruby --version
+
+# Check Node.js version (should be 20+)
+node --version
+
+# Check PostgreSQL
+psql --version
+
+# Check Redis
+redis-cli --version
+
+# Check Git
+git --version
+```
+
+## Repository Setup
+
+### 1. Fork and Clone
+
+```bash
+# Fork the repository on GitHub first
+# Then clone your fork
+git clone https://github.com/YOUR_USERNAME/chatwoot.git
+cd chatwoot
+
+# Add upstream remote for syncing
+git remote add upstream https://github.com/chatwoot/chatwoot.git
+
+# Verify remotes
+git remote -v
+# Should show:
+# origin    https://github.com/YOUR_USERNAME/chatwoot.git (fetch)
+# origin    https://github.com/YOUR_USERNAME/chatwoot.git (push)
+# upstream  https://github.com/chatwoot/chatwoot.git (fetch)
+# upstream  https://github.com/chatwoot/chatwoot.git (push)
+```
+
+### 2. Branch Strategy
+
+```bash
+# Create a development branch
+git checkout -b develop
+
+# For feature work, create feature branches
+git checkout -b feature/your-feature-name
+
+# Keep your fork synced
+git fetch upstream
+git checkout develop
+git merge upstream/develop
+git push origin develop
+```
+
+## Environment Configuration
+
+### 1. Environment File Setup
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Open the file for editing
+nano .env
+```
+
+### 2. Basic Configuration
+
+Update your `.env` file with the following essential settings:
+
+```bash
+# Rails Environment
+RAILS_ENV=development
+NODE_ENV=development
+
+# Application URLs
+FRONTEND_URL=http://localhost:3000
+FORCE_SSL=false
+
+# Database Configuration
+DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
+REDIS_URL=redis://localhost:6379/0
+
+# Email Configuration (for development)
+MAILER_SENDER_EMAIL=dev@chatwoot.local
+SMTP_ADDRESS=localhost
+SMTP_PORT=1025
+
+# File Storage
+ACTIVE_STORAGE_SERVICE=local
+
+# Development Features
+ENABLE_DEVELOPMENT_FEATURES=true
+LOG_LEVEL=debug
+RAILS_LOG_LEVEL=debug
+
+# Disable SSL in development
+SMTP_ENABLE_STARTTLS_AUTO=false
+SMTP_TLS=false
+```
+
+### 3. Generate Secret Keys
+
+```bash
+# Generate secret key base
+bundle exec rails secret
+
+# Add to your .env file
+echo "SECRET_KEY_BASE=your-generated-secret" >> .env
+```
+
+## Database Setup
+
+### 1. Database Creation
+
+```bash
+# Create development and test databases
+bundle exec rails db:create
+
+# Expected output:
+# Created database 'chatwoot_development'
+# Created database 'chatwoot_test'
+```
+
+### 2. Database Migration
+
+```bash
+# Run database migrations
+bundle exec rails db:migrate
+
+# Check migration status
+bundle exec rails db:migrate:status
+```
+
+### 3. Database Seeding
+
+```bash
+# Seed the database with sample data
+bundle exec rails db:seed
+
+# This creates:
+# - Sample account
+# - Admin user
+# - Sample conversations
+# - Test data for development
+```
+
+### 4. Test Database Setup
+
+```bash
+# Prepare test database
+RAILS_ENV=test bundle exec rails db:create
+RAILS_ENV=test bundle exec rails db:migrate
+```
+
+## Dependency Installation
+
+### 1. Ruby Dependencies
+
+```bash
+# Install Ruby gems
+bundle install
+
+# If you encounter issues, try:
+bundle install --retry=3
+
+# For development and test gems
+bundle install --with development test
+```
+
+### 2. Node.js Dependencies
+
+```bash
+# Install Node.js packages
+pnpm install
+
+# If pnpm is not available, install it first:
+npm install -g pnpm
+
+# Clear cache if needed
+pnpm store prune
+```
+
+### 3. Additional Tools
+
+```bash
+# Install Foreman for process management
+gem install foreman
+
+# Install MailHog for email testing (optional)
+# macOS
+brew install mailhog
+
+# Ubuntu/Debian
+sudo apt-get install mailhog
+
+# Or download binary from GitHub releases
+```
+
+## Application Startup
+
+### 1. Using Foreman (Recommended)
+
+```bash
+# Start all services with Foreman
+foreman start -f Procfile.dev
+
+# This starts:
+# - Rails server (port 3000)
+# - Webpack dev server
+# - Sidekiq worker
+```
+
+### 2. Manual Startup
+
+If you prefer to run services separately:
+
+```bash
+# Terminal 1: Rails server
+bundle exec rails server -p 3000
+
+# Terminal 2: Webpack dev server
+pnpm run dev
+
+# Terminal 3: Sidekiq worker
+bundle exec sidekiq
+
+# Terminal 4: MailHog (optional)
+mailhog
+```
+
+### 3. Verify Installation
+
+Once all services are running, verify your setup:
+
+- **Web Application**: http://localhost:3000
+- **API Health Check**: http://localhost:3000/api
+- **Sidekiq Web UI**: http://localhost:3000/sidekiq
+- **MailHog**: http://localhost:8025 (if running)
+
+## Initial Login
+
+### Default Credentials
+
+After seeding the database, you can log in with:
+
+```
+Email: john@acme.inc
+Password: Password1!
+```
+
+### Creating Additional Users
+
+```bash
+# Access Rails console
+bundle exec rails console
+
+# Create a new user
+user = User.create!(
+  name: "Your Name",
+  email: "your.email@example.com",
+  password: "Password123!",
+  password_confirmation: "Password123!"
+)
+
+# Make user an administrator
+user.account_users.first.update!(role: 'administrator')
+```
+
+## Development Workflow
+
+### 1. Code Quality Setup
+
+```bash
+# Install pre-commit hooks (optional but recommended)
+# Create .git/hooks/pre-commit
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/sh
+# Run RuboCop
+bundle exec rubocop --parallel
+
+# Run ESLint
+pnpm run lint
+
+# Run tests
+bundle exec rspec --fail-fast
+EOF
+
+chmod +x .git/hooks/pre-commit
+```
+
+### 2. Running Tests
+
+```bash
+# Run Ruby tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/models/user_spec.rb
+
+# Run JavaScript tests
+pnpm run test
+
+# Run E2E tests (requires Playwright)
+pnpm exec playwright install
+pnpm run test:e2e
+
+# Run tests with coverage
+COVERAGE=true bundle exec rspec
+```
+
+### 3. Code Linting and Formatting
+
+```bash
+# Ruby linting with RuboCop
+bundle exec rubocop
+
+# Auto-fix Ruby issues
+bundle exec rubocop -a
+
+# JavaScript linting
+pnpm run lint
+
+# Auto-fix JavaScript issues
+pnpm run lint:fix
+
+# Format code with Prettier
+pnpm run format
+```
+
+## IDE Configuration
+
+### VS Code Setup
+
+Create `.vscode/settings.json`:
+
+```json
+{
+  "ruby.intellisense": "rubyLocate",
+  "ruby.codeCompletion": "rcodetools",
+  "ruby.format": "rubocop",
+  "editor.formatOnSave": true,
+  "editor.rulers": [120],
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "eslint.autoFixOnSave": true,
+  "prettier.requireConfig": true,
+  "ruby.rubocop.executePath": "./bin/",
+  "ruby.rubocop.onSave": true
+}
+```
+
+Create `.vscode/extensions.json`:
+
+```json
+{
+  "recommendations": [
+    "rebornix.ruby",
+    "wingrunr21.vscode-ruby",
+    "bradlc.vscode-tailwindcss",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "ms-vscode.vscode-typescript-next",
+    "shopify.ruby-lsp"
+  ]
+}
+```
+
+### RubyMine Setup
+
+1. **Open Project**: File → Open → Select chatwoot directory
+2. **Configure Ruby SDK**: File → Project Structure → SDKs → Add Ruby SDK
+3. **Database Connection**: Database tool window → Add PostgreSQL connection
+4. **Code Style**: File → Settings → Editor → Code Style → Import scheme
+
+## Debugging Setup
+
+### Rails Debugging
+
+Add to your code for debugging:
+
+```ruby
+# Using Pry (recommended)
+binding.pry
+
+# Using built-in debugger
+debugger
+
+# Using byebug
+byebug
+```
+
+### JavaScript Debugging
+
+```javascript
+// Browser debugging
+console.log('Debug info:', variable);
+debugger;
+
+// Node.js debugging
+console.log('Debug info:', variable);
+```
+
+### Database Debugging
+
+```bash
+# Rails console
+bundle exec rails console
+
+# Database console
+bundle exec rails dbconsole
+
+# Check queries in development log
+tail -f log/development.log | grep -E "(SELECT|INSERT|UPDATE|DELETE)"
+```
+
+## Performance Optimization
+
+### Development Performance
+
+```bash
+# Use Spring for faster Rails commands
+bundle exec spring binstub --all
+
+# Precompile assets for faster loading
+bundle exec rails assets:precompile
+
+# Use parallel testing
+bundle exec rspec --parallel
+
+# Monitor memory usage
+ps aux | grep -E "(ruby|node)" | head -10
+```
+
+### Database Performance
+
+```ruby
+# Add to config/environments/development.rb for query analysis
+config.active_record.verbose_query_logs = true
+
+# Enable query plan logging
+config.active_record.dump_schema_after_migration = false
+```
+
+## Troubleshooting Setup Issues
+
+### Common Setup Problems
+
+<Accordion title="Bundle install fails">
+**Error**: `An error occurred while installing pg`
+
+**Solution**:
+```bash
+# macOS
+brew install postgresql
+bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
+
+# Ubuntu/Debian
+sudo apt-get install libpq-dev
+bundle install
+```
+</Accordion>
+
+<Accordion title="Database connection refused">
+**Error**: `could not connect to server: Connection refused`
+
+**Solution**:
+```bash
+# Check if PostgreSQL is running
+sudo systemctl status postgresql
+
+# Start PostgreSQL
+sudo systemctl start postgresql
+
+# macOS with Homebrew
+brew services start postgresql
+```
+</Accordion>
+
+<Accordion title="Redis connection refused">
+**Error**: `Redis::CannotConnectError`
+
+**Solution**:
+```bash
+# Check if Redis is running
+redis-cli ping
+
+# Start Redis
+sudo systemctl start redis
+
+# macOS with Homebrew
+brew services start redis
+```
+</Accordion>
+
+<Accordion title="Webpack compilation fails">
+**Error**: `Module not found` or compilation errors
+
+**Solution**:
+```bash
+# Clear webpack cache
+rm -rf tmp/cache/webpacker
+
+# Reinstall node modules
+rm -rf node_modules
+pnpm install
+
+# Restart webpack dev server
+pnpm run dev
+```
+</Accordion>
+
+### Verification Commands
+
+```bash
+# Check all services are running
+ps aux | grep -E "(rails|sidekiq|webpack|mailhog)"
+
+# Test database connection
+bundle exec rails runner "puts ActiveRecord::Base.connection.execute('SELECT 1').first"
+
+# Test Redis connection
+bundle exec rails runner "puts Redis.new.ping"
+
+# Check application health
+curl http://localhost:3000/api
+```
+
+## Next Steps
+
+After successful setup:
+
+1. **Explore the Codebase**: Familiarize yourself with the project structure
+2. **Read Contributing Guidelines**: Review code standards and workflow
+3. **Pick Your First Issue**: Look for "good first issue" labels
+4. **Join the Community**: Connect with other contributors
+
+### Useful Development Commands
+
+```bash
+# Generate new migration
+bundle exec rails generate migration AddColumnToTable column:type
+
+# Generate new model
+bundle exec rails generate model ModelName attribute:type
+
+# Generate new controller
+bundle exec rails generate controller ControllerName
+
+# Run specific migration
+bundle exec rails db:migrate:up VERSION=20231201000000
+
+# Rollback migration
+bundle exec rails db:rollback STEP=1
+
+# Reset database (careful!)
+bundle exec rails db:drop db:create db:migrate db:seed
+```
+
+## Getting Help
+
+If you encounter issues during setup:
+
+- **Check Common Errors**: See [Common Errors](./common-errors) guide
+- **Environment Variables**: Review [Environment Variables](./environment-variables) guide
+- **GitHub Issues**: Search existing issues or create a new one
+- **Discord Community**: Join the Chatwoot Discord server
+- **Documentation**: Check the official documentation
+
+---
+
+You're now ready to start developing with Chatwoot! Your development environment should be fully functional and ready for contribution.