Development Workflow Guide

Development Workflow Guide

Complete guide to the development and deployment workflow for iSu Technologies applications.

---

🏗️ Development Environment

Directory Structure

Development: /projects/active/ (3.1GB total) Production: /var/www/ (24GB total)

Development Projects

Project	Size	Git Status	Production Location
thrive-send-b2b2g	2.0GB	✅ Clean	/var/www/thrivesend/
isutech-prospect-iq	696MB	✅ Clean	/var/www/prospect-iq/
umdoni-website	271MB	✅ Clean	/var/www/umdoni/
mnyandu-portfolio_from_root	147MB	✅ Clean	/var/www/nhlanhla-portfolio/
matchmind	19MB	✅ Clean	/var/www/matchmind/ (stopped)
iSuMonitor	7.6MB	⚪ No Git	/var/www/monitor/
autoslip	1.7MB	✅ Clean	Service only
MyProfile	56KB	⚪ No Git	Personal docs

Note: Development happens directly on the production server at /projects/active/ due to Mac hardware constraints.

Working over SSH? Use tmux

Since dev work happens on the server over SSH, run your sessions inside tmux so they survive disconnects, support split panes, and can be detached and reattached. See the tmux Tutorial for the full walkthrough or the Cheat Sheet for keybindings.

---

🔄 Standard Development Workflow

1. Navigate to Development Directory

# Navigate to development project
cd /projects/active/<project-name>

# Check Git status
git status

# Check current branch
git branch

2. Make Changes

# Create feature branch (recommended)
git checkout -b feature/your-feature-name

# Or work on main/master (for small changes)
git checkout main

# Edit files
nano src/components/YourComponent.tsx

3. Test Locally

For Next.js Applications:

# Install dependencies (if needed)
npm install

# Run development server
npm run dev
# Opens at http://localhost:3000

# Run tests (if available)
npm test

# Build to verify
npm run build

For FastAPI Applications:

# Activate virtual environment
source venv/bin/activate

# Install dependencies (if needed)
pip install -r requirements.txt

# Run development server
uvicorn app.main:app --reload --port 8000

# Run tests (if available)
pytest

# Check code quality
flake8 app/
black app/ --check

4. Commit Changes

# Check what changed
git status
git diff

# Stage changes
git add .
# Or stage specific files
git add src/components/YourComponent.tsx

# Commit with descriptive message
git commit -m "Add new feature: description of what you did

- Bullet point 1
- Bullet point 2

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

# View commit history
git log --oneline -5

5. Push to GitHub

# Push to remote repository
git push origin main
# Or for feature branch
git push origin feature/your-feature-name

# If branch doesn't exist on remote
git push -u origin feature/your-feature-name

6. Deploy to Production

See deployment procedures below for specific application types.

---

🚀 Deployment Procedures

Deploying Next.js Applications (PM2)

Applications: ThriveSend, SANSA Frontend, iSuTech Backend

# 1. Navigate to production directory
cd /var/www/<app-name>

# 2. Backup current build (optional but recommended)
cp -r .next .next.backup-$(date +%Y%m%d)

# 3. Pull latest changes from Git
git pull origin main

# 4. Install dependencies
npm install

# 5. Build application
npm run build

# 6. Restart PM2 process
pm2 restart <app-name>

# 7. Verify deployment
pm2 status
pm2 logs <app-name> --lines 50

# 8. Test application
curl http://localhost:<port>
# Or visit https://<domain>

Example: Deploying ThriveSend

cd /var/www/thrivesend
cp -r .next .next.backup-$(date +%Y%m%d)
git pull origin main
npm install
npm run build
pm2 restart thrivesend
pm2 logs thrivesend --lines 50

---

Deploying FastAPI Applications (systemd)

Applications: SANSA Backend, Tumi Backend, SACE Backend

# 1. Navigate to production directory
cd /var/www/<app-name>

# 2. Backup current code (optional)
tar -czf ../backup-<app-name>-$(date +%Y%m%d).tar.gz app/

# 3. Pull latest changes
git pull origin main

# 4. Activate virtual environment
source venv/bin/activate

# 5. Install new dependencies
pip install -r requirements.txt

# 6. Run database migrations (if applicable)
alembic upgrade head

# 7. Deactivate virtual environment
deactivate

# 8. Restart systemd service
sudo systemctl restart <service-name>

# 9. Verify deployment
sudo systemctl status <service-name>
sudo journalctl -u <service-name> -n 50

# 10. Test API
curl http://localhost:<port>/api/health
# Or visit https://<domain>/api/docs

Example: Deploying SANSA Backend

cd /var/www/sansa-backend
tar -czf ../backup-sansa-backend-$(date +%Y%m%d).tar.gz app/
git pull origin main
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
deactivate
sudo systemctl restart sansa-backend
sudo systemctl status sansa-backend
sudo journalctl -u sansa-backend -n 50
curl http://localhost:8003/api/v1/health

---

Deploying Next.js Applications (systemd)

Applications: SACE Frontend, ProspectIQ Frontend

# 1. Navigate to production directory
cd /var/www/<app-name>

# 2. Backup current build
cp -r .next .next.backup-$(date +%Y%m%d)

# 3. Pull latest changes
git pull origin main

# 4. Install dependencies
npm install

# 5. Build application
npm run build

# 6. Restart systemd service
sudo systemctl restart <service-name>

# 7. Verify deployment
sudo systemctl status <service-name>
sudo journalctl -u <service-name> -n 50

# 8. Test application
curl http://localhost:<port>

Example: Deploying SACE Frontend

cd /var/www/sace-frontend
cp -r .next .next.backup-$(date +%Y%m%d)
git pull origin main
npm install
npm run build
sudo systemctl restart sace-frontend
sudo systemctl status sace-frontend
sudo journalctl -u sace-frontend -n 50
curl http://localhost:3000

---

Deploying Static Sites

Applications: Tumi Frontend, Umdoni, Portfolio, DocsHub

# 1. Navigate to production directory
cd /var/www/<app-name>

# 2. Backup current build
tar -czf ../backup-<app-name>-$(date +%Y%m%d).tar.gz .

# 3. Pull latest changes
git pull origin main

# 4. If build step required (e.g., React/Vue)
npm install
npm run build

# 5. No restart needed - nginx serves files automatically

# 6. Verify deployment
curl https://<domain>

# 7. Check nginx logs
sudo tail -f /var/log/nginx/access.log

Example: Deploying DocsHub (Astro Starlight)

cd /var/www/docs/repo
git pull origin main
npm ci --production
npx astro build
# Site built to: /var/www/docs/repo/dist
# Nginx automatically serves updated files
# Note: auto-updated every 10 min via cron

---

Deploying ProspectIQ (5 Services)

ProspectIQ requires careful orchestration due to its 5-service architecture:

# 1. Navigate to production directory
cd /var/www/prospect-iq

# 2. Backup current code
tar -czf ../backup-prospectiq-$(date +%Y%m%d).tar.gz .

# 3. Pull latest changes
git pull origin main

# 4. Install backend dependencies (if backend changed)
cd backend
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
deactivate
cd ..

# 5. Install frontend dependencies (if frontend changed)
cd frontend
npm install
npm run build
cd ..

# 6. Restart services in correct order
# Stop workers first
sudo systemctl stop prospectiq-celery-beat
sudo systemctl stop prospectiq-celery
sudo systemctl stop prospectiq-worker

# Restart API
sudo systemctl restart prospectiq-api

# Restart frontend
sudo systemctl restart prospectiq-frontend

# Start workers
sudo systemctl start prospectiq-worker
sudo systemctl start prospectiq-celery
sudo systemctl start prospectiq-celery-beat

# 7. Verify all services
sudo systemctl status prospectiq-api prospectiq-frontend \
  prospectiq-celery prospectiq-celery-beat prospectiq-worker

# 8. Check logs
sudo journalctl -u prospectiq-api -n 20
sudo journalctl -u prospectiq-celery -n 20

---

🔧 Development Best Practices

Git Workflow

Branch Strategy:

# Main branch for production-ready code
main / master

# Feature branches for new features
feature/add-user-authentication
feature/improve-dashboard

# Bugfix branches for bug fixes
bugfix/fix-login-error
bugfix/correct-typo

# Hotfix branches for urgent production fixes
hotfix/critical-security-patch

Commit Message Format:

Brief summary of change (50 chars or less)

More detailed explanation if needed. Wrap at 72 characters.
- Bullet points for specific changes
- Multiple bullets if needed

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Good Commit Messages:

• ✅ “Add user authentication with JWT tokens”
• ✅ “Fix database connection timeout issue”
• ✅ “Update dashboard UI with new charts”
• ❌ “Fixed stuff”
• ❌ “WIP”
• ❌ “Changes”

Code Review Checklist

Before deploying to production:

• Code tested locally
• Tests passing (if applicable)
• No console errors
• Environment variables updated (if needed)
• Database migrations tested (if applicable)
• Git commits pushed to remote
• Code reviewed (if team workflow)
• Production backup created
• Deployment plan documented
• Rollback plan ready

Environment Variables

Development (.env.local):

# Development environment variables
DATABASE_URL=postgresql://user:pass@localhost:5432/dev_db
API_URL=http://localhost:8000
DEBUG=true

Production (.env.production):

# Production environment variables
DATABASE_URL=postgresql://user:pass@localhost:5432/prod_db
API_URL=https://api.domain.com
DEBUG=false

Security:

• ✅ NEVER commit .env files to Git
• ✅ Add .env* to .gitignore
• ✅ Use strong passwords
• ✅ Rotate secrets regularly
• ✅ Use environment-specific configs

---

🔄 Database Migrations

Alembic (Python/FastAPI)

Create Migration:

cd /projects/active/<project-name>
source venv/bin/activate
alembic revision --autogenerate -m "Description of changes"

Review Migration:

# Check generated migration file
cat alembic/versions/<revision_id>_description.py

# Edit if needed
nano alembic/versions/<revision_id>_description.py

Test Migration (Development):

# Apply migration
alembic upgrade head

# Verify changes
psql -U user -d dev_db -c "\dt"

# Rollback if needed
alembic downgrade -1

Deploy Migration (Production):

cd /var/www/<app-name>
source venv/bin/activate
alembic upgrade head
deactivate
sudo systemctl restart <service-name>

Prisma (Node.js/Next.js)

Create Migration:

cd /projects/active/<project-name>
npx prisma migrate dev --name description_of_changes

Deploy Migration (Production):

cd /var/www/<app-name>
npx prisma migrate deploy
pm2 restart <app-name>
# Or
sudo systemctl restart <service-name>

---

🚨 Rollback Procedures

Rolling Back Code

PM2 Applications:

# 1. Navigate to production directory
cd /var/www/<app-name>

# 2. Restore previous build
rm -rf .next
mv .next.backup-YYYYMMDD .next

# 3. Restart PM2
pm2 restart <app-name>

# Or restore from Git
git log --oneline -10
git reset --hard <previous-commit-hash>
npm install
npm run build
pm2 restart <app-name>

Systemd Applications:

# 1. Navigate to production directory
cd /var/www/<app-name>

# 2. Restore from backup
rm -rf app
tar -xzf ../backup-<app-name>-YYYYMMDD.tar.gz

# 3. Restart service
sudo systemctl restart <service-name>

# Or restore from Git
git log --oneline -10
git reset --hard <previous-commit-hash>
source venv/bin/activate
pip install -r requirements.txt
deactivate
sudo systemctl restart <service-name>

Rolling Back Database

PostgreSQL:

# 1. Stop application
sudo systemctl stop <service-name>

# 2. Restore database backup
sudo -u postgres psql -d <database-name> < ~/backups/backup-YYYYMMDD.sql

# 3. Restart application
sudo systemctl start <service-name>

Alembic:

# Rollback to previous migration
cd /var/www/<app-name>
source venv/bin/activate
alembic downgrade -1
deactivate
sudo systemctl restart <service-name>

---

📊 Monitoring Deployments

Comprehensive Monitoring Commands

For detailed monitoring commands and troubleshooting, see the Server Monitoring Quick Reference.

Verify Deployment Success

Check Service Status:

# Systemd services
sudo systemctl status <service-name>

# PM2 processes
pm2 status

Check Logs:

# Systemd logs
sudo journalctl -u <service-name> -f

# PM2 logs
pm2 logs <app-name>

# Nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

Test Endpoints:

# Health checks
curl http://localhost:<port>/api/health
curl https://<domain>/api/health

# Application access
curl https://<domain>

# Check response time
curl -w "@curl-format.txt" -o /dev/null -s https://<domain>

Common Issues After Deployment

Issue	Solution
Service won’t start	Check logs: sudo journalctl -u <service> -n 100
502 Bad Gateway	Service not running or wrong port
404 Not Found	Nginx config issue or wrong domain
Import errors (Python)	Missing dependencies: pip install -r requirements.txt
Module not found (Node)	Missing dependencies: npm install
Database connection failed	Check DATABASE_URL in .env
Permission denied	Check file ownership: chown -R www-data:www-data /var/www/<app>

---

📦 Backup Strategy

Regular Backups

Code Backups:

# Git repositories (automatic via GitHub)
cd /var/www/<app-name>
git remote -v
git status

# Manual backup before deployment
tar -czf ~/backups/backup-<app-name>-$(date +%Y%m%d).tar.gz /var/www/<app-name>

Database Backups:

# PostgreSQL backup
sudo -u postgres pg_dump <database-name> > ~/backups/<database>-$(date +%Y%m%d).sql

# Backup all databases
sudo -u postgres pg_dumpall > ~/backups/all-databases-$(date +%Y%m%d).sql

# Backup with compression
sudo -u postgres pg_dump <database-name> | gzip > ~/backups/<database>-$(date +%Y%m%d).sql.gz

Automated Backups (Cron):

# Edit crontab
crontab -e

# Add daily database backup at 2 AM
0 2 * * * sudo -u postgres pg_dump sansa_production > ~/backups/sansa-$(date +\%Y\%m\%d).sql

# Add weekly cleanup of old backups (keep 30 days)
0 3 * * 0 find ~/backups -name "*.sql" -mtime +30 -delete

---

🔒 Security Considerations

Development Security

• ✅ Use different credentials for development and production
• ✅ Never commit secrets to Git
• ✅ Use .env files for environment variables
• ✅ Add .env* to .gitignore
• ✅ Rotate API keys regularly
• ✅ Use SSH keys for Git authentication

Production Security

• ✅ Use HTTPS for all applications
• ✅ Keep SSL certificates updated (auto-renewal via certbot)
• ✅ Use strong database passwords
• ✅ Restrict database access to localhost
• ✅ Enable UFW firewall
• ✅ Regular security updates: sudo apt update && sudo apt upgrade
• ✅ Use systemd service hardening
• ✅ Implement rate limiting on API endpoints

Secrets Management

Protected Files:

# AutoSlip secrets
/projects/active/autoslip/.env.backup-*
/projects/active/autoslip/google-credentials.json

# Application secrets
/var/www/*/. env
/var/www/*/.env.production

File Permissions:

# Restrict .env files
chmod 600 /var/www/<app>/.env

# Restrict service account keys
chmod 600 /var/www/<app>/google-credentials.json

---

📝 Quick Reference

Development to Production Flow

1. Work on feature in /projects/active/<project>/
2. Test locally (npm run dev / uvicorn --reload)
3. Commit changes to Git
4. Push to GitHub
5. Navigate to /var/www/<project>/
6. Pull latest changes
7. Install dependencies
8. Build application
9. Restart service
10. Verify deployment
11. Monitor logs

Common Commands

# Development
cd /projects/active/<project>
git status
npm run dev  # or uvicorn app.main:app --reload

# Production
cd /var/www/<project>
git pull origin main
npm install && npm run build  # or pip install -r requirements.txt
pm2 restart <app>  # or sudo systemctl restart <service>
pm2 logs <app>  # or sudo journalctl -u <service> -f

---

📞 Support & Resources

Internal Documentation

• Hetzner Server Management - Infrastructure details
• Hetzner Server Guide - Operations procedures

External Resources

• Git Documentation
• Next.js Deployment
• FastAPI Deployment
• PM2 Documentation
• Systemd Service Management

---

Last Updated: 02/01/2026 | Document Owner: Development Team | Version: 1.0