stiftung-management-system/DEVELOPMENT_WORKFLOW.md

🚀 Development Workflow Guide

🔄 Complete Development Process

Step 1: Make Changes Safely (Local Development)

# 1. Start development environment (isolated from production)
docker-compose -f compose.dev.yml up -d

# 2. Make your code changes in the /app directory
# - Edit Python files, templates, models, etc.
# - Changes automatically reload in development server

# 3. Test your changes
# - Access: http://localhost:8081 (Django app)
# - Access: http://localhost:8082 (Paperless)
# - Database: localhost:5433 (completely separate from production)

# 4. Run tests if needed
docker-compose -f compose.dev.yml exec web python manage.py test

# 5. When done testing, stop development
docker-compose -f compose.dev.yml down

Step 2: Commit Changes (Git Version Control)

# 1. Stage your changes
git add .

# 2. Commit with descriptive message
git commit -m "Add new feature: enhanced user management"

# 3. Push to GitHub (but NOT to main branch yet)
git push origin main

Step 3: Deploy to Production (Automated)

When you push to the main branch, GitHub Actions automatically:

1. Builds the Docker images
2. Runs tests (if any fail, deployment stops)
3. Deploys to production server
4. Preserves production database and secrets
5. Updates only the code, not the data

🛡️ Environment Separation Details

Development Environment (compose.dev.yml)

• Database: stiftung_dev (port 5433)
• Data: Completely isolated test data
• Secrets: Hardcoded safe values
• Purpose: Safe testing without any risk

Production Environment (compose.yml)

• Database: stiftung (internal to server)
• Data: Real user data (Destinatäre, Förderungen, etc.)
• Secrets: Secure tokens from server's .env file
• Purpose: Live system for real users

🔒 Safety Guarantees

What CAN'T Break Production:

✅ Code changes in development
✅ Database changes in development
✅ Testing new features locally
✅ Experimenting with different configurations

What COULD Affect Production:

⚠️ Pushing broken code to main branch
⚠️ Database migration issues (rare)
⚠️ Configuration changes in compose.yml

🧪 Testing New Features

For Small Changes:

1. Edit code in /app directory
2. Test in development (localhost:8081)
3. If good → commit and push

For Database Changes:

1. Create migration: docker-compose -f compose.dev.yml exec web python manage.py makemigrations
2. Test migration: docker-compose -f compose.dev.yml exec web python manage.py migrate
3. Verify in development environment
4. If good → commit and push (migration will run automatically in production)

For Major Features:

1. Create feature branch: git checkout -b feature/new-feature
2. Develop and test extensively in development environment
3. Create Pull Request on GitHub
4. Review and merge to main when ready

🚀 Deployment Process

graph LR
    A[Local Changes] --> B[Development Testing]
    B --> C[Git Commit]
    C --> D[Push to GitHub]
    D --> E[GitHub Actions]
    E --> F[Automatic Production Deployment]
    F --> G[Live on vhtv-stiftung.de]

🆘 Emergency Procedures

If Something Breaks in Production:

1. Rollback: git revert <commit-hash> and push
2. Quick Fix: Make fix, test locally, commit and push
3. Check Logs: GitHub Actions shows deployment logs

If Development Environment Has Issues:

1. Reset: docker-compose -f compose.dev.yml down -v
2. Rebuild: docker-compose -f compose.dev.yml up -d --build
3. Re-migrate: docker-compose -f compose.dev.yml exec web python manage.py migrate

📊 Current Status Check

# Check what's running
docker ps

# Development environment status
docker-compose -f compose.dev.yml ps

# View logs
docker-compose -f compose.dev.yml logs web