Update Procedures Guide¶

This guide covers the procedures for updating KrakenHashes deployments, including pre-update checks, update processes, and rollback procedures.

⚠️ IMPORTANT: KrakenHashes is currently in v0.1.0-alpha. Breaking changes are expected between versions. Always review release notes and test updates in a non-production environment first.

Pre-Update Checklist¶

Before beginning any update, complete the following checklist:

1. Review Release Notes¶

Check the release notes for breaking changes
Review migration scripts included in the release
Identify any configuration changes required
Note any new environment variables or removed features

2. Backup Current System¶

# Backup database
docker-compose exec postgres pg_dump -U krakenhashes krakenhashes > backup_$(date +%Y%m%d_%H%M%S).sql

# Backup configuration files
cp -r /home/zerkereod/Programming/passwordCracking/krakenhashes/.env backup/.env.$(date +%Y%m%d_%H%M%S)
cp -r /home/zerkereod/Programming/passwordCracking/kh-backend/config backup/config_$(date +%Y%m%d_%H%M%S)

# Backup data directory
tar -czf backup/data_$(date +%Y%m%d_%H%M%S).tar.gz /home/zerkereod/Programming/passwordCracking/kh-backend/data

3. Check System Health¶

# Check service status
docker-compose ps

# Verify no active jobs
docker-compose exec backend curl -s http://localhost:8080/api/v1/health

# Check agent connections
docker-compose logs backend | grep -i "agent.*connected" | tail -n 20

4. Document Current Version¶

# Record current versions
docker-compose exec backend /app/krakenhashes --version > current_version.txt
docker-compose exec postgres psql -U krakenhashes -c "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1;"

5. Plan Maintenance Window¶

Notify users of planned downtime
Schedule update during low-activity period
Prepare rollback plan
Assign responsible personnel

Updating Docker Deployments¶

Standard Update Process¶

Stop Current Services

cd /home/zerkereod/Programming/passwordCracking/krakenhashes
docker-compose down

Pull Latest Code

git fetch origin
git checkout tags/v0.2.0  # Replace with target version
# OR for latest development
git checkout master
git pull origin master

Review Configuration Changes

# Check for new environment variables
diff .env.example .env

# Apply any new required variables
nano .env

Build and Start Services

# Build new images
docker-compose build --no-cache

# Start services
docker-compose up -d

# Monitor startup
docker-compose logs -f

Incremental Updates (Development)¶

For development environments with frequent updates:

# Quick rebuild and restart
docker-compose down
git pull origin master
docker-compose up -d --build backend
docker-compose logs -f backend

Database Migration Procedures¶

Automatic Migrations¶

Migrations are automatically applied on backend startup. Monitor the process:

# Watch migration logs
docker-compose logs backend | grep -i migration

# Verify migration status
docker-compose exec postgres psql -U krakenhashes -d krakenhashes -c "SELECT version, dirty FROM schema_migrations ORDER BY version DESC LIMIT 5;"

Manual Migration Control¶

For production environments requiring manual migration control:

Disable Auto-Migration
```
# In .env, set:
AUTO_MIGRATE=false
```

Apply Migrations Manually

cd backend

# View pending migrations
make migrate-status

# Apply all pending migrations
make migrate-up

# Apply specific version
migrate -path db/migrations -database "$DATABASE_URL" goto 20240115120000

Verify Migration Success

# Check migration history
docker-compose exec postgres psql -U krakenhashes -d krakenhashes -c "SELECT * FROM schema_migrations;"

# Test critical tables
docker-compose exec postgres psql -U krakenhashes -d krakenhashes -c "\dt"

Handling Failed Migrations¶

If a migration fails:

Check Migration Status

# Check if migration is dirty
docker-compose exec postgres psql -U krakenhashes -d krakenhashes -c "SELECT * FROM schema_migrations WHERE dirty = true;"

Fix Dirty Migration

# Force version (use with caution)
cd backend
migrate -path db/migrations -database "$DATABASE_URL" force 20240115120000

# Then retry
make migrate-up

Agent Update Process¶

Coordinated Agent Updates¶

Prepare New Agent Binary

# New agent binaries are typically included in backend updates
# Verify new version is available
docker-compose exec backend ls -la /data/krakenhashes/binaries/

Notify Connected Agents

# Agents will receive update notifications via WebSocket
# Monitor agent update status in backend logs
docker-compose logs -f backend | grep -i "agent.*update"

Manual Agent Update (if auto-update fails)

# On each agent machine
cd /path/to/agent
./update.sh  # If provided

# Or manually:
systemctl stop krakenhashes-agent
wget https://your-server/api/v1/binaries/agent/latest -O krakenhashes-agent
chmod +x krakenhashes-agent
systemctl start krakenhashes-agent

Agent Compatibility Check¶

Before updating:

# Check agent versions
docker-compose exec backend curl -s http://localhost:8080/api/v1/agents | jq '.[] | {id, version, last_seen}'

# Verify compatibility matrix in release notes

Rollback Procedures¶

Quick Rollback (Docker)¶

Stop Current Services
```
docker-compose down
```

Restore Previous Version

# Checkout previous version
git checkout tags/v0.1.0  # Previous version

# Restore configuration
cp backup/.env.20240115_120000 .env

# Rebuild and start
docker-compose up -d --build

Restore Database (if schema changed)

# Stop backend to prevent connections
docker-compose stop backend

# Restore database
docker-compose exec -T postgres psql -U krakenhashes -d krakenhashes < backup_20240115_120000.sql

# Restart backend
docker-compose start backend

Rollback with Data Preservation¶

For rollbacks that need to preserve new data:

Export New Data

# Export specific tables with new data
docker-compose exec postgres pg_dump -U krakenhashes -t job_executions -t hashes --data-only krakenhashes > new_data.sql

Perform Rollback Follow standard rollback procedure

Reimport Preserved Data

# Carefully reimport compatible data
docker-compose exec -T postgres psql -U krakenhashes -d krakenhashes < new_data.sql

Version Compatibility¶

Compatibility Matrix¶

Component	Backend	Agent	Frontend	Database Schema
v0.1.0	0.1.0	0.1.0	0.1.0	19
v0.2.0	0.2.0	0.1.0-0.2.0	0.2.0	22
v1.0.0	1.0.0	1.0.0	1.0.0	30

Note: During alpha, assume all components must be updated together unless release notes specify otherwise.

Checking Compatibility¶

# Check all component versions
docker-compose exec backend /app/krakenhashes --version
docker-compose exec backend curl -s http://localhost:8080/api/v1/system/info

# Check schema version
docker-compose exec postgres psql -U krakenhashes -c "SELECT MAX(version) FROM schema_migrations;"

Post-Update Verification¶

1. System Health Checks¶

# Backend health
curl -s https://localhost:8443/api/v1/health | jq .

# Database connectivity
docker-compose exec backend curl -s http://localhost:8080/api/v1/system/db-check

# Frontend accessibility
curl -I https://localhost:8443

2. Functional Verification¶

# Test authentication
curl -X POST https://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

# Check agent connectivity
docker-compose logs backend | grep -i "websocket.*agent" | tail -n 10

# Verify job creation (with auth token)
curl -X GET https://localhost:8443/api/v1/jobs \
  -H "Authorization: Bearer $TOKEN"

3. Data Integrity Checks¶

-- Connect to database
docker-compose exec postgres psql -U krakenhashes -d krakenhashes

-- Check critical tables
SELECT COUNT(*) FROM users;
SELECT COUNT(*) FROM agents;
SELECT COUNT(*) FROM hashlists;
SELECT COUNT(*) FROM job_executions WHERE status = 'running';

-- Verify migrations
SELECT * FROM schema_migrations ORDER BY version DESC LIMIT 5;

4. Performance Verification¶

# Check resource usage
docker stats --no-stream

# Monitor logs for errors
docker-compose logs --tail=100 backend | grep -i error

# Check response times
time curl -s https://localhost:8443/api/v1/health

Troubleshooting¶

Common Update Issues¶

1. Migration Failures¶

# Check migration logs
docker-compose logs backend | grep -E "(migration|migrate)"

# Reset dirty migration
cd backend
migrate -path db/migrations -database "$DATABASE_URL" force VERSION_NUMBER

2. Container Start Failures¶

# Check detailed logs
docker-compose logs backend
docker-compose logs postgres

# Verify file permissions
ls -la /home/zerkereod/Programming/passwordCracking/kh-backend/data

# Check disk space
df -h

3. Agent Connection Issues¶

# Restart agent connections
docker-compose restart backend

# Check WebSocket logs
docker-compose logs backend | grep -i websocket

# Verify agent API keys are still valid
docker-compose exec postgres psql -U krakenhashes -c "SELECT * FROM agents WHERE active = true;"

4. Frontend Loading Issues¶

# Clear browser cache and cookies
# Rebuild frontend
docker-compose up -d --build app

# Check nginx logs
docker-compose logs app

Emergency Procedures¶

If the system becomes unresponsive:

Preserve Logs

docker-compose logs > emergency_logs_$(date +%Y%m%d_%H%M%S).txt

Force Stop
```
docker-compose down -v
```

Clean Start

docker system prune -f
docker-compose up -d --build

Contact Support
Provide emergency logs
Document steps leading to failure
Note any error messages

Best Practices¶

Always Test Updates
Use staging environment
Test core functionality
Verify agent connectivity
Schedule Wisely
Update during maintenance windows
Avoid updates during active cracking jobs
Coordinate with users
Document Everything
Record version changes
Note configuration modifications
Log any issues encountered
Monitor Post-Update
Watch logs for 24 hours
Check performance metrics
Gather user feedback
Maintain Backups
Keep multiple backup versions
Test restore procedures regularly
Store backups securely

Conclusion¶

Updating KrakenHashes requires careful planning and execution, especially during the alpha phase. Always prioritize data safety and system availability. When in doubt, test in a non-production environment first.

For additional support or questions about specific update scenarios, consult the documentation or contact the development team.