Command Cheat Sheet

Quick reference for common commands for the New Hires Reporting System.

Docker Compose

Start & Stop

# Pull latest images
docker-compose -f docker-compose.prod.yml pull

# Start all services (foreground)
docker-compose -f docker-compose.prod.yml up

# Start all services (background)
docker-compose -f docker-compose.prod.yml up -d

# Stop all services
docker-compose -f docker-compose.prod.yml down

# Stop and remove volumes (CAREFUL - deletes data!)
docker-compose -f docker-compose.prod.yml down -v

# Restart all services
docker-compose -f docker-compose.prod.yml restart

# Restart specific service
docker-compose -f docker-compose.prod.yml restart backend
docker-compose -f docker-compose.prod.yml restart workers

---

Logs

# All logs (live)
docker-compose -f docker-compose.prod.yml logs -f

# Backend logs only
docker-compose -f docker-compose.prod.yml logs -f backend

# Workers logs only
docker-compose -f docker-compose.prod.yml logs -f workers

# Frontend logs only
docker-compose -f docker-compose.prod.yml logs -f frontend

# Last 100 lines
docker-compose -f docker-compose.prod.yml logs --tail=100 workers

# With timestamps
docker-compose -f docker-compose.prod.yml logs -f -t backend

# Since specific time
docker-compose -f docker-compose.prod.yml logs --since "2025-01-15T10:00:00" backend

---

Status & Health

# Service status
docker-compose -f docker-compose.prod.yml ps

# Resource usage
docker stats

# Health check (backend)
curl http://localhost:8000/health

# Health check (frontend)
curl -I http://localhost:8080

# Database health
docker exec newhires-db pg_isready -U newhires

---

Production Commands

# Authenticate to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  878796852397.dkr.ecr.us-east-1.amazonaws.com

# Pull latest images
docker-compose -f docker-compose.prod.yml pull

# Start production
docker-compose -f docker-compose.prod.yml up -d

# Run database migrations
docker exec newhires-backend alembic upgrade head

# View production logs
docker-compose -f docker-compose.prod.yml logs -f workers

# Restart production
docker-compose -f docker-compose.prod.yml restart

# Stop production
docker-compose -f docker-compose.prod.yml down

---

Debugging

# Shell into backend container
docker exec -it newhires-backend bash

# Shell into worker container
docker exec -it newhires-workers bash

# Shell into frontend container
docker exec -it newhires-frontend sh

# View environment variables
docker exec newhires-backend env
docker exec newhires-workers env | grep AWS

# Check network
docker network inspect newhires-reporting_default

# Container details
docker inspect newhires-backend
docker inspect newhires-workers

---

Cleanup

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune -a

# Remove unused volumes (CAREFUL!)
docker volume prune

# Clean everything except running containers
docker system prune -a --volumes

# Nuclear option (removes EVERYTHING including data)
docker-compose -f docker-compose.prod.yml down -v
docker system prune -a --volumes -f

---

Log Analysis

# Find errors
docker logs newhires-workers | grep -i error

# Find Bedrock API activity
docker logs newhires-workers | grep -i bedrock

# Find validation events
docker logs newhires-backend | grep -E "validation|validate"

# Count errors
docker logs newhires-workers | grep -i error | wc -l

# Check Bedrock token usage
docker logs newhires-workers | grep "tokens used"

# Export logs
docker logs newhires-backend > backend-logs.txt
docker logs newhires-workers > workers-logs.txt
docker logs newhires-frontend > frontend-logs.txt

---

Health Checks

# Backend health (pretty JSON)
curl http://localhost:8000/health | jq

# Frontend health
curl -I http://localhost:8080

# Database health
docker exec newhires-db psql -U newhires -d newhires -c "SELECT 1;"

# Worker health (check logs)
docker logs newhires-workers --tail=20

# Check from container
docker exec newhires-backend curl http://localhost:8000/health

---

Environment Management

# View current environment variables
docker exec newhires-workers env | grep AWS
docker exec newhires-backend env | grep POSTGRES

# Test configuration
docker-compose -f docker-compose.prod.yml config

# Validate docker-compose.prod.yml
docker-compose -f docker-compose.prod.yml config --quiet && echo "Valid" || echo "Invalid"

---

Database Operations

# Backup database
docker exec newhires-db pg_dump -U newhires newhires > backup_$(date +%Y%m%d).sql

# Backup database (compressed)
docker exec newhires-db pg_dump -U newhires newhires | gzip > backup_$(date +%Y%m%d).sql.gz

# Restore database
cat backup_20241124.sql | docker exec -i newhires-db psql -U newhires -d newhires

# Access database CLI
docker exec -it newhires-db psql -U newhires -d newhires

# Check job queue
docker exec newhires-db psql -U newhires -d newhires -c \
  "SELECT status, COUNT(*) FROM correction_jobs GROUP BY status;"

# List tables
docker exec newhires-db psql -U newhires -d newhires -c "\dt"

---

Worker Management

# Scale workers up
docker-compose -f docker-compose.prod.yml up -d --scale workers=3

# Scale workers down
docker-compose -f docker-compose.prod.yml up -d --scale workers=1

# Check worker status
docker ps | grep newhires-workers

# View worker logs (live)
docker logs -f newhires-workers

# Check for Bedrock errors
docker logs newhires-workers | grep -i "error\|exception"

# Restart workers
docker-compose -f docker-compose.prod.yml restart workers

---

Network Troubleshooting

# Test backend from host
curl http://localhost:8000/health

# Test backend from frontend container
docker exec newhires-frontend wget -O- http://backend:8000/health

# Test backend from worker container
docker exec newhires-workers curl http://backend:8000/health

# Check ports in use
sudo netstat -tlnp | grep -E '8000|8080'

# Check Docker networks
docker network ls
docker network inspect newhires-reporting_default

---

Performance Monitoring

# Real-time resource usage
docker stats

# CPU usage only
docker stats --no-stream --format "{{.Container}}: {{.CPUPerc}}"

# Memory usage only
docker stats --no-stream --format "{{.Container}}: {{.MemUsage}}"

# Disk usage
docker system df
docker volume ls

# Database size
docker exec newhires-db psql -U newhires -d newhires -c \
  "SELECT pg_size_pretty(pg_database_size('newhires'));"

---

File Operations

# Copy file to container
docker cp file.txt newhires-backend:/app/

# Copy file from container
docker cp newhires-backend:/app/file.txt ./

# View file in container
docker exec newhires-backend cat /app/file.txt

# View logs in container
docker exec newhires-backend tail -f /var/log/app.log

---

Quick Fixes

# Restart everything
docker-compose -f docker-compose.prod.yml restart

# Pull and restart
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d

# Fresh start (keeps data)
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d
docker exec newhires-backend alembic upgrade head

# Hard reset (DELETES ALL DATA!)
docker-compose -f docker-compose.prod.yml down -v
docker system prune -a
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d
docker exec newhires-backend alembic upgrade head

---

API Testing

# Health check
curl http://localhost:8000/health

# API documentation
open http://localhost:8000/docs

# Test file upload (example)
curl -X POST http://localhost:8000/api/v1/files \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/file.txt"

# Check job status
curl http://localhost:8000/api/v1/jobs/{job_id}

---

AWS Bedrock Testing

# Test AWS credentials
docker exec newhires-workers python3 -c "
import boto3
print(boto3.client('sts').get-caller-identity())
"

# Test Bedrock access
docker exec newhires-workers python3 -c "
import boto3
client = boto3.client('bedrock-runtime', region_name='us-east-1')
print('Bedrock client created successfully')
"

# List available models
aws bedrock list-foundation-models --region us-east-1 \
  --query 'modelSummaries[?contains(modelId, \`claude\`)].modelId'

# Check Bedrock token usage from logs
docker logs newhires-workers | grep "tokens used" | tail -10

---

Emergency Commands

# Kill all containers
docker kill $(docker ps -q)

# Remove all containers
docker rm $(docker ps -a -q)

# Remove all images
docker rmi $(docker images -q)

# Complete reset (DESTRUCTIVE!)
docker-compose -f docker-compose.prod.yml down -v
docker system prune -a --volumes -f
docker network prune -f

---

Access Points

# Local deployment
Frontend:     http://localhost:8080
Backend:      http://localhost:8000
API Docs:     http://localhost:8000/docs

# Production (replace with your domain)
Frontend:     https://your-domain.com
Backend:      https://api.your-domain.com
API Docs:     https://api.your-domain.com/docs

---

Quick Diagnostics Script

#!/bin/bash
# quick-check.sh - Run all basic checks

echo "=== Service Status ==="
docker-compose -f docker-compose.prod.yml ps

echo -e "\n=== Backend Health ==="
curl -s http://localhost:8000/health | jq

echo -e "\n=== Frontend Health ==="
curl -I http://localhost:8080

echo -e "\n=== Database Health ==="
docker exec newhires-db pg_isready -U newhires

echo -e "\n=== Resource Usage ==="
docker stats --no-stream

echo -e "\n=== Recent Worker Logs ==="
docker logs newhires-workers --tail=20

echo -e "\n=== Recent Errors ==="
docker logs newhires-workers --tail=50 | grep -i error

echo -e "\n=== Job Queue Status ==="
docker exec newhires-db psql -U newhires -d newhires -c \
  "SELECT status, COUNT(*) FROM correction_jobs GROUP BY status;"

echo -e "\n=== AWS Bedrock Status ==="
docker exec newhires-workers env | grep AWS_REGION

Save as quick-check.sh, make executable with chmod +x quick-check.sh, then run with ./quick-check.sh

---

Update Procedure

# 1. Update IMAGE_TAG in .env
nano .env

# 2. Re-authenticate to ECR (if needed)
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  878796852397.dkr.ecr.us-east-1.amazonaws.com

# 3. Pull new images
docker-compose -f docker-compose.prod.yml pull

# 4. Stop services
docker-compose -f docker-compose.prod.yml down

# 5. Start with new images
docker-compose -f docker-compose.prod.yml up -d

# 6. Run database migrations
docker exec newhires-backend alembic upgrade head

# 7. Verify health
curl http://localhost:8000/health
docker-compose -f docker-compose.prod.yml logs --tail=50

---

Keyboard Shortcuts (Browser)

Ctrl + Shift + R  - Hard refresh (clear cache)
F12               - Open developer console
Ctrl + Shift + I  - Open developer tools
Ctrl + R          - Refresh page
Esc               - Stop loading

---

Next Steps

• API Endpoints Reference
• AWS Bedrock Troubleshooting
• Common Issues
• Environment Variables