From ffb429239dff995a25383ee63548071e93adffbc Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 27 Jul 2025 17:53:30 +0530 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=92=20Implement=20comprehensive=20depl?= =?UTF-8?q?oyment=20control=20system?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create protected branch strategy: main (production) โ† staging โ† development - Configure Railway deployment controls with environment-specific settings - Add GitHub branch protection setup script with automated configuration - Implement comprehensive deployment control documentation: - Complete deployment control guide with Railway configuration - Quick reference development workflow guide - Detailed deployment checklist for all phases - Pull request template with quality gates ๐Ÿ›ก๏ธ Safety Features: - main branch: Protected, requires PR approval, auto-deploys to production - staging branch: Optional pre-production testing environment - development branch: Safe zone for all development work, no auto-deploy - Emergency procedures: Hotfix and rollback processes documented ๐Ÿš€ Workflow Benefits: - Prevents accidental production deployments - Maintains development velocity on safe branches - Clear promotion path: development โ†’ staging โ†’ production - Automated quality gates and approval processes ๐Ÿ“‹ Setup Instructions: - Run ./scripts/setup_branch_protection.sh for GitHub protection - Configure Railway to deploy only from designated branches - Use DEVELOPMENT_WORKFLOW.md for daily development guide Generated with Claude Code Co-Authored-By: Claude --- .github/PULL_REQUEST_TEMPLATE.md | 111 ++++++++ .railway.env.example | 43 +++ CLAUDE.md | 8 +- DEVELOPMENT_WORKFLOW.md | 144 ++++++++++ docs/deployment/deployment-checklist.md | 235 ++++++++++++++++ docs/deployment/deployment-control-guide.md | 281 ++++++++++++++++++++ docs_update_summary.txt | 25 +- railway.json | 9 + railway.staging.json | 20 ++ scripts/setup_branch_protection.sh | 143 ++++++++++ 10 files changed, 1007 insertions(+), 12 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .railway.env.example create mode 100644 DEVELOPMENT_WORKFLOW.md create mode 100644 docs/deployment/deployment-checklist.md create mode 100644 docs/deployment/deployment-control-guide.md create mode 100644 railway.staging.json create mode 100755 scripts/setup_branch_protection.sh diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..9d881c7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,111 @@ +# Pull Request + +## Description + + +## Type of Change + +- [ ] ๐Ÿ› Bug fix (non-breaking change which fixes an issue) +- [ ] โœจ New feature (non-breaking change which adds functionality) +- [ ] ๐ŸŽจ UI/UX improvement (changes to user interface or experience) +- [ ] ๐Ÿ”ง Refactoring (code change that neither fixes a bug nor adds a feature) +- [ ] ๐Ÿ“š Documentation update +- [ ] ๐Ÿš€ Performance improvement +- [ ] ๐Ÿ” Security improvement +- [ ] ๐Ÿค– New AI agent (marketplace agent addition) +- [ ] โšก Breaking change (fix or feature that would cause existing functionality to not work as expected) + +## Agent Development (if applicable) + +- [ ] Agent type: Webhook / API +- [ ] Agent category: ________________ +- [ ] Price: _______ AED +- [ ] N8N workflow configured (webhook agents) +- [ ] BaseAgent catalog entry created +- [ ] Component-based template implemented +- [ ] Dynamic pricing using {{ agent.price }} +- [ ] Standardized toast messages + +## Testing Checklist + +- [ ] Tested locally with `python manage.py runserver` +- [ ] All existing tests pass +- [ ] New tests added for new functionality +- [ ] Database migrations tested (if applicable) +- [ ] Tested with different user permission levels +- [ ] Mobile/responsive design tested +- [ ] Cross-browser compatibility verified +- [ ] Agent functionality tested end-to-end (if applicable) + +## Security Checklist + +- [ ] No hardcoded secrets or API keys +- [ ] Input validation implemented +- [ ] Authentication/authorization properly handled +- [ ] CSRF protection in place for forms +- [ ] File upload validation (if applicable) +- [ ] XSS prevention measures implemented +- [ ] SQL injection prevention (using Django ORM) + +## Deployment Readiness + +- [ ] Environment variables documented +- [ ] Static files optimization completed +- [ ] Database migration strategy confirmed +- [ ] Rollback plan prepared +- [ ] Documentation updated +- [ ] CLAUDE.md updated (if needed) + +## Code Quality + +- [ ] Code follows project conventions +- [ ] Functions and variables properly named +- [ ] No duplicate code +- [ ] Error handling implemented +- [ ] Logging added where appropriate +- [ ] Performance considerations addressed + +## Branch Strategy + +- [ ] `development` โ† Feature/bug fix +- [ ] `staging` โ† Ready for staging deployment and testing +- [ ] `main` โ† Ready for production deployment (requires approval) + +## Related Issues + +Fixes #(issue_number) +Closes #(issue_number) +Related to #(issue_number) + +## Screenshots (if applicable) + + +## Additional Notes + + +--- + +## For Reviewers + +### Review Checklist +- [ ] Code quality and conventions followed +- [ ] Security considerations addressed +- [ ] Testing coverage adequate +- [ ] Documentation complete and accurate +- [ ] No breaking changes (or properly documented) +- [ ] Performance impact considered +- [ ] Deployment requirements understood + +### Agent Review (if applicable) +- [ ] Agent follows established patterns +- [ ] Component-based template architecture used +- [ ] Proper error handling and user feedback +- [ ] Marketplace integration complete +- [ ] Pricing and wallet validation correct + +### Security Review +- [ ] No security vulnerabilities introduced +- [ ] Authentication and authorization correct +- [ ] Input validation comprehensive +- [ ] File handling secure (if applicable) +- [ ] Payment processing secure (if applicable) \ No newline at end of file diff --git a/.railway.env.example b/.railway.env.example new file mode 100644 index 0000000..b160b0b --- /dev/null +++ b/.railway.env.example @@ -0,0 +1,43 @@ +# Railway Environment Variables Template +# Copy this to Railway dashboard for environment-specific deployments + +# Django Settings +DEBUG=False +SECRET_KEY=your-production-secret-key-here +ALLOWED_HOSTS=your-domain.railway.app,www.quantumtaskai.com + +# Database +DATABASE_URL=postgresql://user:password@host:port/database + +# Stripe Configuration +STRIPE_PUBLISHABLE_KEY=pk_live_your_publishable_key +STRIPE_SECRET_KEY=sk_live_your_secret_key +STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret + +# Email Configuration +EMAIL_HOST=smtp.gmail.com +EMAIL_PORT=587 +EMAIL_USE_TLS=True +EMAIL_HOST_USER=your-email@gmail.com +EMAIL_HOST_PASSWORD=your-app-password + +# Admin Configuration +DJANGO_SUPERUSER_USERNAME=admin +DJANGO_SUPERUSER_EMAIL=admin@quantumtaskai.com +DJANGO_SUPERUSER_PASSWORD=your-secure-admin-password + +# N8N Webhook URLs (Production) +N8N_WEBHOOK_DATA_ANALYZER=https://your-n8n-instance.com/webhook/data-analyzer +N8N_WEBHOOK_SOCIAL_ADS=https://your-n8n-instance.com/webhook/social-ads +N8N_WEBHOOK_JOB_POSTING=https://your-n8n-instance.com/webhook/job-posting +N8N_WEBHOOK_FIVE_WHYS=https://your-n8n-instance.com/webhook/five-whys + +# Security Settings +SECURE_SSL_REDIRECT=True +SECURE_HSTS_SECONDS=31536000 +SECURE_HSTS_INCLUDE_SUBDOMAINS=True +SECURE_FRAME_DENY=True + +# Deployment Control +DEPLOYMENT_ENVIRONMENT=production # production, staging, development +BRANCH_NAME=main # Track which branch is deployed \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 44f0e69..0ec02d9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,10 +28,12 @@ MAKE ALL FIXES AND CODE CHANGES AS SIMPLE AS HUMANLY POSSIBLE. THEY SHOULD ONLY - **โš™๏ธ Operations:** [docs/operations/](./docs/operations/) - Database management, troubleshooting, maintenance **Quick Links:** -- [Domain Change Guide](./docs/deployment/domain-change-guide.md) - Complete domain change instructions +- [Development Workflow](./DEVELOPMENT_WORKFLOW.md) - **๐Ÿš€ START HERE** - Daily development workflow +- [Deployment Control Guide](./docs/deployment/deployment-control-guide.md) - Branch strategy and Railway control +- [Subagents Guide](./docs/development/subagents-guide.md) - AI development assistants +- [Auto-Documentation System](./docs/development/auto-documentation-system.md) - Automated documentation updates - [Railway Deployment](./docs/deployment/railway-deployment.md) - Production deployment guide - [Environment Variables](./docs/deployment/environment-variables.md) - Complete environment reference -- [Auto-Documentation System](./docs/development/auto-documentation-system.md) - Automated documentation updates ## Project Overview @@ -483,4 +485,4 @@ curl http://localhost:8000/health/ Always run `python manage.py check_db` before making database-related changes to ensure proper configuration. --- -Last updated: 2025-07-27 17:00:00 +Last updated: Last updated: 2025-07-27 17:47:37 diff --git a/DEVELOPMENT_WORKFLOW.md b/DEVELOPMENT_WORKFLOW.md new file mode 100644 index 0000000..dcdc2f3 --- /dev/null +++ b/DEVELOPMENT_WORKFLOW.md @@ -0,0 +1,144 @@ +# ๐Ÿš€ Development Workflow - Quick Reference + +## Current Branch Strategy +``` +main (production) โ† Railway Auto-Deploy ON +โ”‚ +โ”œโ”€โ”€ staging (pre-production) โ† Railway Staging Environment +โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€ development (active development) โ† Railway Auto-Deploy OFF +``` + +## ๐Ÿ“‹ Daily Development Workflow + +### 1. Start New Work +```bash +# Always start from development branch +git checkout development +git pull origin development + +# Create feature branch (optional but recommended) +git checkout -b feature/your-feature-name +``` + +### 2. Make Changes & Test +```bash +# Make your changes +# Test locally +python manage.py runserver + +# Use subagents for specialized tasks: +# - "Create new agent" โ†’ agent-architect subagent +# - "Fix Django error" โ†’ django-debugger subagent +# - "Security review" โ†’ security-auditor subagent +# - "Optimize template" โ†’ template-optimizer subagent +``` + +### 3. Commit to Development +```bash +# Commit your changes +git add . +git commit -m "โœจ Add your feature description" + +# Push to development (safe - no auto-deploy) +git push origin development +``` + +### 4. Test on Staging (When Ready) +```bash +# Merge to staging for testing +git checkout staging +git merge development +git push origin staging + +# This deploys to Railway staging environment +# Test at: https://staging-quantumtaskai.railway.app +``` + +### 5. Deploy to Production (Manual Approval Required) +```bash +# Only when staging tests pass +# Create Pull Request: staging โ†’ main +# Requires approval before merging +# Auto-deploys to production after merge +``` + +## ๐Ÿ›ก๏ธ Safety Features + +### โœ… What's Protected +- **main branch**: Requires PR approval, auto-deploys to production +- **Railway production**: Only deploys from main branch +- **Accidental deployments**: Prevented by branch protection + +### โœ… What's Safe +- **development branch**: No auto-deployment, safe for experimentation +- **feature branches**: No auto-deployment, safe for testing +- **Local testing**: Always safe with `python manage.py runserver` + +## ๐Ÿšจ Emergency Procedures + +### Hotfix Critical Production Bug +```bash +git checkout main +git checkout -b hotfix/critical-fix +# Make minimal fix +git checkout main +git merge hotfix/critical-fix +git push origin main # Deploys immediately +``` + +### Rollback Production +```bash +# Option 1: Git rollback +git checkout main +git reset --hard HEAD~1 +git push --force-with-lease origin main + +# Option 2: Railway dashboard rollback +# Use Railway UI to rollback to previous deployment +``` + +## ๐Ÿ“ž Quick Commands + +### Development Server +```bash +./run_dev.sh # Quick start with migrations +python manage.py runserver # Manual start +``` + +### Testing +```bash +python manage.py check --deploy # Production readiness +python tests/test_agent_name.py # Test specific agent +``` + +### Documentation +```bash +./scripts/update_docs_manual.sh # Update documentation +/update-docs # Claude Code slash command +``` + +### Branch Protection +```bash +./scripts/setup_branch_protection.sh # Setup GitHub protections +``` + +## ๐ŸŽฏ Key Points + +1. **Development branch = Safe zone** - No auto-deployment +2. **Staging branch = Test environment** - Deploys to staging +3. **Main branch = Production** - Requires approval, auto-deploys +4. **All new work** should start on development branch +5. **Subagents available** for specialized development tasks +6. **Auto-documentation** updates with each commit + +## ๐Ÿ”— Related Documentation + +- [Complete Deployment Control Guide](./docs/deployment/deployment-control-guide.md) +- [Subagents Guide](./docs/development/subagents-guide.md) +- [Auto-Documentation System](./docs/development/auto-documentation-system.md) +- [Railway Deployment Guide](./docs/deployment/railway-deployment.md) + +--- + +**Remember**: development branch is your safe space - experiment freely! ๐Ÿงช \ No newline at end of file diff --git a/docs/deployment/deployment-checklist.md b/docs/deployment/deployment-checklist.md new file mode 100644 index 0000000..3a435a8 --- /dev/null +++ b/docs/deployment/deployment-checklist.md @@ -0,0 +1,235 @@ +# Deployment Checklist + +Use this checklist to ensure safe and successful deployments to Railway. + +## Pre-Development Setup โœ… + +### Branch Protection (One-time setup) +- [ ] Run `./scripts/setup_branch_protection.sh` +- [ ] Verify main branch requires PR approval +- [ ] Confirm staging branch protection (optional) +- [ ] Set development as default branch for PRs + +### Railway Configuration (One-time setup) +- [ ] Production service connected to `main` branch only +- [ ] Staging service connected to `staging` branch (optional) +- [ ] Auto-deploy enabled only for designated branches +- [ ] Environment variables configured per environment +- [ ] Custom domain configured for production + +## Development Phase ๐Ÿ› ๏ธ + +### Before Starting Work +- [ ] Working on `development` branch +- [ ] Local environment up to date: `git pull origin development` +- [ ] Virtual environment activated +- [ ] Dependencies installed: `pip install -r requirements.txt` + +### During Development +- [ ] Regular local testing: `python manage.py runserver` +- [ ] Use appropriate subagents for specialized tasks: + - [ ] `agent-architect` for new agents + - [ ] `django-expert` for Django development + - [ ] `security-auditor` for security reviews + - [ ] `template-optimizer` for UI improvements + - [ ] `django-debugger` for error fixes + +### Code Quality Checks +- [ ] Code follows project conventions +- [ ] No hardcoded secrets or API keys +- [ ] Environment variables used for configuration +- [ ] Error handling implemented +- [ ] Input validation in place +- [ ] CSRF protection on forms +- [ ] Authentication/authorization properly handled + +## Pre-Staging Deployment ๐Ÿงช + +### Code Readiness +- [ ] All changes committed to `development` branch +- [ ] Local tests passing: `python manage.py test` +- [ ] Django system check: `python manage.py check --deploy` +- [ ] No migration conflicts +- [ ] Static files collection works: `python manage.py collectstatic --dry-run` + +### Documentation +- [ ] CLAUDE.md updated (if needed) +- [ ] Feature documentation added +- [ ] API changes documented (if applicable) +- [ ] Environment variable changes noted + +### Database Migrations +- [ ] Migrations created: `python manage.py makemigrations` +- [ ] Migration files reviewed for correctness +- [ ] Backward compatibility confirmed +- [ ] Migration tested locally + +## Staging Deployment ๐ŸŽญ + +### Deployment Process +- [ ] Merge `development` โ†’ `staging` +- [ ] Push to remote: `git push origin staging` +- [ ] Verify staging deployment successful +- [ ] Check staging logs for errors + +### Staging Testing +- [ ] Full application workflow testing +- [ ] All agent functionality working +- [ ] Payment processing working (test mode) +- [ ] File uploads working correctly +- [ ] Email functionality working +- [ ] Database migrations applied correctly +- [ ] Static files serving correctly +- [ ] Mobile/responsive design verified +- [ ] Cross-browser compatibility checked + +### Performance Testing +- [ ] Page load times acceptable +- [ ] Agent processing times normal +- [ ] Database query performance good +- [ ] No memory leaks or high resource usage + +### Security Testing +- [ ] Authentication working correctly +- [ ] Authorization enforced properly +- [ ] CSRF protection active +- [ ] XSS prevention in place +- [ ] File upload security working +- [ ] Payment security measures active + +## Pre-Production Deployment ๐Ÿš€ + +### Final Approval +- [ ] Staging tests completed successfully +- [ ] Client/stakeholder approval received +- [ ] Security audit passed +- [ ] Performance benchmarks met +- [ ] All acceptance criteria satisfied + +### Production Readiness +- [ ] Production environment variables ready +- [ ] Database backup completed +- [ ] SSL certificates valid +- [ ] Custom domain configuration ready +- [ ] Monitoring and alerting configured + +### Deployment Strategy +- [ ] Rollback plan prepared and tested +- [ ] Deployment window scheduled (if needed) +- [ ] Team notified of deployment +- [ ] Post-deployment verification plan ready + +## Production Deployment ๐ŸŽฏ + +### Deployment Process +- [ ] Create Pull Request: `staging` โ†’ `main` +- [ ] PR review completed and approved +- [ ] All CI/CD checks passing +- [ ] Merge PR to `main` branch +- [ ] Verify automatic deployment triggered + +### Post-Deployment Verification +- [ ] Application responding correctly +- [ ] Health check endpoint working: `/health/` +- [ ] Database migrations applied successfully +- [ ] Static files serving correctly +- [ ] Custom domain working +- [ ] SSL certificate active +- [ ] Payment processing working +- [ ] Email functionality working + +### Monitoring +- [ ] Application logs monitored for errors +- [ ] Performance metrics within normal range +- [ ] Error rates within acceptable limits +- [ ] User feedback monitored +- [ ] Support channels ready for issues + +## Post-Deployment ๐Ÿ“Š + +### Success Confirmation +- [ ] All critical user flows tested in production +- [ ] Analytics and monitoring data normal +- [ ] No critical errors in logs +- [ ] Customer support tickets minimal +- [ ] Team notified of successful deployment + +### Documentation Updates +- [ ] Deployment notes recorded +- [ ] Version/release notes updated +- [ ] Any configuration changes documented +- [ ] Lessons learned documented + +### Environment Cleanup +- [ ] Development branch updated from main +- [ ] Staging branch synced with main +- [ ] Feature branches cleaned up (if any) +- [ ] Local environment updated + +## Emergency Procedures ๐Ÿšจ + +### If Deployment Fails +- [ ] Check Railway deployment logs +- [ ] Review application error logs +- [ ] Verify environment variables +- [ ] Check database migration status +- [ ] Consider immediate rollback if critical + +### Rollback Process +- [ ] Use Railway dashboard rollback feature, OR +- [ ] Git rollback: `git reset --hard HEAD~1` and force push +- [ ] Verify rollback successful +- [ ] Investigate and fix issue +- [ ] Plan re-deployment + +### Communication +- [ ] Notify team of deployment status +- [ ] Update stakeholders on any issues +- [ ] Document any problems encountered +- [ ] Plan fixes for next deployment + +## Environment-Specific Checklists + +### Staging Environment +- [ ] DEBUG=True for better error visibility +- [ ] Test Stripe keys used +- [ ] Test email configuration +- [ ] Staging database used +- [ ] Test domain configured + +### Production Environment +- [ ] DEBUG=False for security +- [ ] Live Stripe keys configured +- [ ] Production email settings +- [ ] Production database +- [ ] Live domain with SSL +- [ ] Performance monitoring active + +## Tools and Commands + +### Useful Commands +```bash +# Check deployment readiness +python manage.py check --deploy + +# Test database connection +python manage.py check_db + +# Collect static files +python manage.py collectstatic --noinput + +# Run security check +python -m bandit -r . -x ./venv/ + +# Check for vulnerabilities +pip-audit +``` + +### Monitoring URLs +- Production: https://www.quantumtaskai.com/health/ +- Staging: https://staging-quantumtaskai.railway.app/health/ +- Railway Dashboard: https://railway.app/dashboard + +--- + +**Remember**: When in doubt, test on staging first! ๐Ÿงช \ No newline at end of file diff --git a/docs/deployment/deployment-control-guide.md b/docs/deployment/deployment-control-guide.md new file mode 100644 index 0000000..a00fff4 --- /dev/null +++ b/docs/deployment/deployment-control-guide.md @@ -0,0 +1,281 @@ +# Deployment Control Guide + +This guide explains how to control deployments to Railway and prevent unwanted automatic deployments while maintaining development velocity. + +## Branch Strategy + +### Branch Structure +``` +main (production) โ† Only deploys to Railway production +โ”‚ +โ”œโ”€โ”€ staging (pre-production) โ† Deploys to Railway staging environment +โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€ development (active development) โ† No automatic deployment + โ”‚ + โ”œโ”€โ”€ feature/new-agent + โ”œโ”€โ”€ feature/ui-improvements + โ””โ”€โ”€ hotfix/critical-bug +``` + +### Branch Purposes + +**`main` Branch (Production)** +- โœ… Protected branch - no direct commits +- โœ… Automatically deploys to Railway production +- โœ… Requires Pull Request approval +- โœ… Must pass all tests and security checks +- โœ… Tagged releases for version tracking + +**`staging` Branch (Pre-Production)** +- โœ… Deploys to Railway staging environment +- โœ… Used for final testing before production +- โœ… Merges from `development` via Pull Request +- โœ… Client preview and acceptance testing + +**`development` Branch (Active Development)** +- โœ… Default branch for all new work +- โœ… No automatic deployment +- โœ… Continuous integration testing +- โœ… Subagent development and testing +- โœ… Documentation updates + +## Railway Deployment Configuration + +### Production Environment (main branch) +```json +{ + "environments": { + "production": { + "variables": { + "DEBUG": "False", + "DEPLOYMENT_ENVIRONMENT": "production", + "BRANCH_NAME": "main" + } + } + } +} +``` + +### Staging Environment (staging branch) +```json +{ + "environments": { + "staging": { + "variables": { + "DEBUG": "True", + "DEPLOYMENT_ENVIRONMENT": "staging", + "BRANCH_NAME": "staging" + } + } + } +} +``` + +## Railway Setup Instructions + +### 1. Production Service Configuration +In Railway dashboard for production service: + +1. **Connect to Repository**: Link to your GitHub repository +2. **Branch Configuration**: Set deployment branch to `main` +3. **Auto Deploy**: Enable automatic deployments from `main` only +4. **Environment Variables**: Use production environment variables +5. **Custom Domain**: Configure www.quantumtaskai.com + +### 2. Staging Service Configuration (Optional but Recommended) +Create a separate Railway service for staging: + +1. **Create New Service**: Deploy from same repository +2. **Branch Configuration**: Set deployment branch to `staging` +3. **Environment Variables**: Use staging environment variables +4. **Subdomain**: Use staging-quantumtaskai.railway.app + +### 3. Environment Variable Management +Copy `.railway.env.example` to Railway dashboard and configure: + +```bash +# Production Environment +DEBUG=False +ALLOWED_HOSTS=www.quantumtaskai.com,quantumtaskai.railway.app +DATABASE_URL=postgresql://production-db-url +STRIPE_SECRET_KEY=sk_live_your_production_key + +# Staging Environment +DEBUG=True +ALLOWED_HOSTS=staging-quantumtaskai.railway.app +DATABASE_URL=postgresql://staging-db-url +STRIPE_SECRET_KEY=sk_test_your_test_key +``` + +## Development Workflow + +### 1. Day-to-Day Development +```bash +# Always work on development branch +git checkout development +git pull origin development + +# Create feature branch for specific work +git checkout -b feature/new-sentiment-agent + +# Make your changes, test locally +python manage.py runserver + +# Commit and push to feature branch +git add . +git commit -m "Add sentiment analysis agent" +git push origin feature/new-sentiment-agent + +# Create Pull Request: feature/new-sentiment-agent โ†’ development +``` + +### 2. Testing on Staging +```bash +# When feature is ready for testing +git checkout staging +git pull origin staging + +# Merge development into staging +git merge development +git push origin staging + +# This triggers deployment to Railway staging environment +# Test at: https://staging-quantumtaskai.railway.app +``` + +### 3. Production Deployment +```bash +# Only when staging tests pass +git checkout main +git pull origin main + +# Create Pull Request: staging โ†’ main +# This requires approval and triggers production deployment +``` + +## Preventing Accidental Deployments + +### 1. GitHub Branch Protection Rules +Configure these rules for `main` branch: + +- โœ… Require pull request reviews (minimum 1) +- โœ… Require status checks to pass +- โœ… Require up-to-date branches +- โœ… Restrict pushes to specific users/teams +- โœ… No force pushes allowed +- โœ… No deletions allowed + +### 2. Railway Auto-Deploy Settings +- โœ… Production service: Deploy only from `main` branch +- โœ… Staging service: Deploy only from `staging` branch +- โœ… No deployment from `development` branch +- โœ… Manual deployment approval (optional extra protection) + +### 3. Pre-Deploy Checks +Add these checks to your workflow: + +```bash +# Before merging to main +python manage.py check --deploy +python manage.py test +python manage.py collectstatic --dry-run + +# Security check +python -m bandit -r . -x ./venv/ + +# Dependency check +pip-audit +``` + +## Emergency Procedures + +### Hotfix Process (Critical Production Bug) +```bash +# Create hotfix from main +git checkout main +git checkout -b hotfix/critical-security-fix + +# Make minimal fix +# Test thoroughly +git add . +git commit -m "๐Ÿšจ HOTFIX: Fix critical security vulnerability" + +# Direct merge to main (emergency only) +git checkout main +git merge hotfix/critical-security-fix +git push origin main + +# Backport to other branches +git checkout development +git merge hotfix/critical-security-fix +git push origin development +``` + +### Rollback Process +```bash +# If production deployment fails +git checkout main +git reset --hard HEAD~1 # Go back one commit +git push --force-with-lease origin main + +# Or use Railway dashboard rollback feature +``` + +## Deployment Checklist + +### Pre-Staging Deployment +- [ ] All tests passing locally +- [ ] Code reviewed by team member +- [ ] Documentation updated +- [ ] Environment variables configured +- [ ] Database migrations tested + +### Pre-Production Deployment +- [ ] Staging environment fully tested +- [ ] Client/stakeholder approval +- [ ] Security audit completed +- [ ] Performance testing passed +- [ ] Backup strategy confirmed +- [ ] Rollback plan prepared + +## Monitoring and Alerts + +### Railway Monitoring +- โœ… Set up deployment notifications +- โœ… Configure health check endpoints +- โœ… Monitor application logs +- โœ… Set up error alerting + +### GitHub Monitoring +- โœ… Enable branch protection notifications +- โœ… Monitor Pull Request activity +- โœ… Track deployment status checks + +## Best Practices + +### Development +- Always work on `development` branch +- Create descriptive commit messages +- Test locally before pushing +- Use feature branches for significant changes +- Keep commits small and focused + +### Testing +- Test all functionality on staging first +- Verify database migrations work correctly +- Check all environment-specific configurations +- Test payment processing in staging environment + +### Security +- Never commit secrets to any branch +- Use environment variables for all sensitive data +- Regular security audits before production deployment +- Monitor for dependency vulnerabilities + +### Documentation +- Update documentation with every feature +- Document deployment procedures +- Maintain accurate environment variable lists +- Keep rollback procedures current + +This workflow ensures that your development work stays safe and controlled while maintaining the ability to deploy quickly when needed. \ No newline at end of file diff --git a/docs_update_summary.txt b/docs_update_summary.txt index 4d7fdde..d87ef0b 100644 --- a/docs_update_summary.txt +++ b/docs_update_summary.txt @@ -1,23 +1,30 @@ === Documentation Auto-Update Summary === -Update Date: 2025-07-27 16:59:10 +Update Date: 2025-07-27 17:47:37 Recent Commits: + - 87397ac ๐Ÿค– Add specialized subagents and auto-documentation system - fa38fbd ๐ŸŽจ Toast standardization and dynamic pricing - safe approach - 10e3bb8 quick agent price remove - - 0b854d5 ๐Ÿ”ง Fix Django admin edit functionality for agent prices Agents Changes: - - docs/development/agent-creation.md + - .claude/agents/agent-architect.md + - .claude/agents/django-debugger.md + - .claude/agents/django-expert.md + - .claude/agents/security-auditor.md + - .claude/agents/template-optimizer.md Documentation Changes: + - AUTO_DOCS_SETUP_COMPLETE.md - CLAUDE.md + - docs/README.md + - docs/development/auto-documentation-system.md -Frontend Changes: - - data_analyzer/templates/data_analyzer/detail.html - - email_writer/templates/email_writer/detail.html - - five_whys_analyzer/templates/five_whys_analyzer/detail.html - - job_posting_generator/templates/job_posting_generator/detail.html - - social_ads_generator/templates/social_ads_generator/detail.html +Backend Changes: + - DOCUMENTATION_UPDATE_SUMMARY.txt + - docs_update_summary.txt + - scripts/auto_update_docs.py + - scripts/setup_git_hooks.sh + - scripts/update_docs_manual.sh Updated Documentation Files: - /home/amit/Desktop/quantum_ai/CLAUDE.md diff --git a/railway.json b/railway.json index 11224bb..06f6b14 100644 --- a/railway.json +++ b/railway.json @@ -7,5 +7,14 @@ "startCommand": "python manage.py migrate --run-syncdb; python manage.py populate_agents; python manage.py reset_admin; python manage.py verify_email admin@quantumtaskai.com --force || true; python manage.py collectstatic --noinput && gunicorn netcop_hub.wsgi:application --bind 0.0.0.0:$PORT --workers 1 --timeout 60", "restartPolicyType": "ON_FAILURE", "restartPolicyMaxRetries": 3 + }, + "environments": { + "production": { + "variables": { + "DEBUG": "False", + "DEPLOYMENT_ENVIRONMENT": "production", + "BRANCH_NAME": "main" + } + } } } \ No newline at end of file diff --git a/railway.staging.json b/railway.staging.json new file mode 100644 index 0000000..af9d091 --- /dev/null +++ b/railway.staging.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://railway.app/railway.schema.json", + "build": { + "builder": "NIXPACKS" + }, + "deploy": { + "startCommand": "python manage.py migrate --run-syncdb; python manage.py populate_agents; python manage.py reset_admin; python manage.py verify_email admin@quantumtaskai.com --force || true; python manage.py collectstatic --noinput && gunicorn netcop_hub.wsgi:application --bind 0.0.0.0:$PORT --workers 1 --timeout 60", + "restartPolicyType": "ON_FAILURE", + "restartPolicyMaxRetries": 3 + }, + "environments": { + "staging": { + "variables": { + "DEBUG": "True", + "DEPLOYMENT_ENVIRONMENT": "staging", + "BRANCH_NAME": "staging" + } + } + } +} \ No newline at end of file diff --git a/scripts/setup_branch_protection.sh b/scripts/setup_branch_protection.sh new file mode 100755 index 0000000..38447da --- /dev/null +++ b/scripts/setup_branch_protection.sh @@ -0,0 +1,143 @@ +#!/bin/bash +# GitHub Branch Protection Setup Script +# Run this script to configure branch protection rules + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +echo -e "${GREEN}๐Ÿ” Setting up GitHub Branch Protection Rules${NC}" +echo "This script will guide you through configuring branch protection for Railway deployment control." +echo "" + +# Check if GitHub CLI is installed +if ! command -v gh &> /dev/null; then + echo -e "${RED}โŒ GitHub CLI (gh) is not installed.${NC}" + echo "Please install GitHub CLI first:" + echo " - macOS: brew install gh" + echo " - Ubuntu: sudo apt install gh" + echo " - Or visit: https://cli.github.com/" + exit 1 +fi + +# Check if user is authenticated +if ! gh auth status &> /dev/null; then + echo -e "${YELLOW}๐Ÿ”‘ You need to authenticate with GitHub first.${NC}" + echo "Run: gh auth login" + exit 1 +fi + +# Get repository information +REPO_OWNER=$(gh repo view --json owner --jq '.owner.login') +REPO_NAME=$(gh repo view --json name --jq '.name') + +echo -e "${GREEN}๐Ÿ“‹ Repository: ${REPO_OWNER}/${REPO_NAME}${NC}" +echo "" + +# Function to create branch protection rule +create_branch_protection() { + local branch=$1 + local description=$2 + + echo -e "${YELLOW}๐Ÿ›ก๏ธ Setting up protection for ${branch} branch (${description})${NC}" + + # Create branch protection rule + gh api repos/${REPO_OWNER}/${REPO_NAME}/branches/${branch}/protection \ + --method PUT \ + --field required_status_checks='{"strict":true,"contexts":[]}' \ + --field enforce_admins=true \ + --field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true,"require_code_owner_reviews":false}' \ + --field restrictions=null \ + --field allow_force_pushes=false \ + --field allow_deletions=false \ + > /dev/null 2>&1 + + if [ $? -eq 0 ]; then + echo -e "${GREEN}โœ… Branch protection enabled for ${branch}${NC}" + else + echo -e "${RED}โŒ Failed to set protection for ${branch}${NC}" + echo "This might be because:" + echo " - You don't have admin permissions on the repository" + echo " - The branch doesn't exist yet" + echo " - GitHub API rate limits" + fi +} + +# Create main branch protection (Production) +echo -e "${GREEN}Setting up main branch protection (Production deployment control)${NC}" +create_branch_protection "main" "Production deployment" + +echo "" + +# Create staging branch protection (Optional) +echo -e "${YELLOW}Do you want to protect the staging branch too? (y/n)${NC}" +read -r setup_staging + +if [[ $setup_staging =~ ^[Yy]$ ]]; then + create_branch_protection "staging" "Staging deployment" +fi + +echo "" + +# Create development branch if it doesn't exist +echo -e "${GREEN}Ensuring development branch exists...${NC}" +git show-ref --verify --quiet refs/heads/development +if [ $? -eq 0 ]; then + echo -e "${GREEN}โœ… Development branch already exists${NC}" +else + echo -e "${YELLOW}๐Ÿ“ Creating development branch...${NC}" + git checkout -b development 2>/dev/null || git checkout development + git push -u origin development +fi + +echo "" + +# Push staging branch if it doesn't exist on remote +echo -e "${GREEN}Ensuring staging branch exists on remote...${NC}" +if git ls-remote --heads origin staging | grep -q staging; then + echo -e "${GREEN}โœ… Staging branch already exists on remote${NC}" +else + echo -e "${YELLOW}๐Ÿ“ Pushing staging branch to remote...${NC}" + git push -u origin staging +fi + +echo "" + +# Set default branch to development +echo -e "${YELLOW}Do you want to set 'development' as the default branch for new PRs? (y/n)${NC}" +read -r set_default + +if [[ $set_default =~ ^[Yy]$ ]]; then + gh api repos/${REPO_OWNER}/${REPO_NAME} \ + --method PATCH \ + --field default_branch='development' \ + > /dev/null 2>&1 + + if [ $? -eq 0 ]; then + echo -e "${GREEN}โœ… Default branch set to development${NC}" + else + echo -e "${RED}โŒ Failed to set default branch${NC}" + fi +fi + +echo "" +echo -e "${GREEN}๐ŸŽ‰ Branch protection setup complete!${NC}" +echo "" +echo -e "${YELLOW}Summary of your deployment control setup:${NC}" +echo "๐Ÿ“ฆ main branch โ†’ Protected, auto-deploys to Railway production" +echo "๐Ÿงช staging branch โ†’ ${setup_staging:+Protected, }deploys to Railway staging" +echo "๐Ÿ› ๏ธ development โ†’ Unprotected, no automatic deployment" +echo "" +echo -e "${GREEN}Next steps:${NC}" +echo "1. Configure Railway to deploy only from 'main' branch" +echo "2. Optionally create staging Railway service for 'staging' branch" +echo "3. Always work on 'development' branch for new features" +echo "4. Use Pull Requests to merge: development โ†’ staging โ†’ main" +echo "" +echo -e "${YELLOW}To complete Railway configuration:${NC}" +echo "1. Go to your Railway dashboard" +echo "2. In your service settings, set 'Source Repo' branch to 'main'" +echo "3. Enable 'Auto Deploy' only for the main branch" +echo "4. For staging, create a separate service connected to 'staging' branch" \ No newline at end of file