Troubleshooting

Common issues and solutions.

Application Won't Start

Check Logs

# Docker
docker-compose logs -f ops-atlas

# Kubernetes
kubectl logs -f deployment/ops-atlas -n ops-atlas

Common Causes

1. Database connection failed

   • Verify DATABASE_URL
   • Check if database is running
   • Test connection: psql $DATABASE_URL

2. Port already in use

   • lsof -i :3000
   • Kill process or change port

3. Missing environment variables

   • Check required vars are set
   • Verify .env file is loaded

Cannot Access Dashboard

Symptoms

• Connection refused
• Blank page
• 502 Bad Gateway

Solutions

# Check if service is running
docker-compose ps

# Check port binding
netstat -tlnp | grep 3000

# Check firewall
ufw status

Slow Performance

Database

-- Check slow queries
SELECT * FROM pg_stat_activity WHERE state = 'active';

-- Analyze tables
ANALYZE;

-- Check indexes
SELECT * FROM pg_stat_user_indexes;

Application

# Check resource usage
docker stats ops-atlas

# Check memory
free -h

# Check CPU
top -p $(pgrep -f ops-atlas)

Authentication Issues

Can't Login

1. Clear browser cookies
2. Check JWT_SECRET is set
3. Verify user exists in database
4. Check LDAP/OAuth configuration

Reset Admin Password

# Via CLI
docker exec ops-atlas ops-atlas user reset-password admin

# Via database
psql -c "UPDATE users SET password='$BCRYPT_HASH' WHERE username='admin'"

Alerts Not Sending

1. Check webhook URLs are correct
2. Test webhook manually:

   curl -X POST $SLACK_WEBHOOK_URL -d '{"text":"test"}'

3. Check network connectivity
4. Review alert rules

Getting Help

1. Search existing issues: GitHub Issues
2. Ask the community: Discord
3. Check logs: Always include relevant logs
4. Provide context: Version, OS, deployment method