Skip to content

README.md

Latest commit

 

History

History
728 lines (511 loc) · 15.1 KB

README.md

File metadata and controls

728 lines (511 loc) · 15.1 KB

Maintenance Overview

This document provides comprehensive information about maintaining the Divemap application, including regular maintenance tasks, troubleshooting procedures, and operational guidelines.

Table of Contents

  1. Overview
  2. Regular Maintenance Tasks
  3. Database Maintenance
  4. Application Maintenance
  5. Infrastructure Maintenance
  6. Security Maintenance
  7. Monitoring and Alerts
  8. Troubleshooting
  9. Database Export/Import

Overview

Regular maintenance is essential for ensuring the reliability, security, and performance of the Divemap application. This document outlines the maintenance procedures and schedules for different components of the system.

Maintenance Objectives

  • Reliability: Ensure consistent application availability
  • Performance: Maintain optimal application performance
  • Security: Keep the application secure against threats
  • Data Integrity: Protect and maintain data quality
  • Compliance: Meet operational and regulatory requirements

Maintenance Schedule

Task Frequency Priority Owner
Security Updates Weekly High DevOps
Database Backups Daily High DevOps
Performance Monitoring Daily Medium DevOps
Log Analysis Weekly Medium DevOps
Dependency Updates Monthly Medium Development
Infrastructure Review Quarterly Low DevOps

Regular Maintenance Tasks

Fly.io Logs Usage

When using fly logs commands for maintenance tasks:

  • Oneshot Commands: Use fly logs -n for one-time log checks and scripts
  • Continuous Monitoring: Use fly logs (without -n) for real-time monitoring
  • Continuous Monitoring: Use fly logs (without -n) for real-time monitoring

Examples:

# Quick log check (oneshot)
fly logs -n -a divemap-backend

# Monitor logs continuously
fly logs -a divemap-backend

Daily Tasks

1. Health Checks

# Check application health
curl -f https://divemap.fly.dev/health
curl -f https://divemap-backend.fly.dev/health

# Check service status
fly status

# Check database connectivity
fly ssh console -C "mysql -u divemap_user -p divemap -e 'SELECT 1'"

2. Backup Verification

# Verify backup completion
ls -la /backups/

# Test backup integrity
mysql -u root -p < /backups/latest_backup.sql

3. Log Review

# Check application logs
fly logs -n

# Check error rates
grep -i error /var/log/application.log | wc -l

# Check performance metrics
curl https://divemap.fly.dev/metrics

Weekly Tasks

1. Security Updates

# Update dependencies
pip install --upgrade -r requirements.txt
npm update

# Check for security vulnerabilities
npm audit
safety check

2. Performance Analysis

# Analyze slow queries
fly ssh console -a divemap-db -C "mysql -u divemap_user -p -e 'SHOW
PROCESSLIST'"

# Check resource usage
fly status

# Analyze response times
curl -w "@curl-format.txt" -o /dev/null -s https://divemap.fly.dev/

3. Log Analysis

# Analyze error patterns
fly logs -n | grep -i error | wc -l

# Check for unusual activity
fly logs -n | grep -i "failed login" | wc -l

# Monitor API usage
fly logs -n | grep -i "rate limit" | wc -l

Monthly Tasks

1. Dependency Updates

# Update Python dependencies
cd backend
source divemap_venv/bin/activate
pip install --upgrade -r requirements.txt

# Update Node.js dependencies
cd frontend
npm update
npm audit fix

2. Database Optimization

# Analyze database performance
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SHOW TABLE STATUS'"

# Check for unused indexes
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SELECT * FROM
information_schema.statistics'"

3. Security Review

# Review access logs
fly logs -n | grep -i "unauthorized"

# Check for suspicious activity
fly logs -n | grep -i "failed"

# Review security headers
curl -I https://divemap.fly.dev/

Database Maintenance

Backup Procedures

Daily Backups

# Create database backup
fly ssh console -a divemap-db -C "mysqldump -u root -p divemap >
/backups/divemap_$(date +%Y%m%d).sql"

# Verify backup integrity
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SELECT COUNT(*) FROM
dive_sites'"

Backup Retention

  • Daily backups: Keep for 7 days
  • Weekly backups: Keep for 4 weeks
  • Monthly backups: Keep for 12 months

Migration Management

Check Migration Status

# Check current migration
fly ssh console -a divemap-backend -C "alembic current"

# List all migrations
fly ssh console -a divemap-backend -C "alembic history"

Run Migrations

# Run pending migrations
fly ssh console -a divemap-backend -C "python run_migrations.py"

# Check migration status
fly ssh console -a divemap-backend -C "alembic current"

Performance Optimization

Query Optimization

# Check slow queries
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SHOW PROCESSLIST'"

# Analyze query performance
fly ssh console -a divemap-db -C "mysql -u root -p -e 'EXPLAIN SELECT * FROM
dive_sites WHERE name LIKE \"%test%\"'"

Index Management

# Check index usage
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SHOW INDEX FROM
dive_sites'"

# Analyze index efficiency
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SELECT * FROM
information_schema.statistics WHERE table_name = \"dive_sites\"'"

Application Maintenance

Code Updates

Backend Updates

# Update backend code
git pull origin main

# Install new dependencies
cd backend
source divemap_venv/bin/activate
pip install -r requirements.txt

# Run tests
python -m pytest tests/ -v

# Deploy updates
fly deploy -a divemap-backend

Frontend Updates

# Update frontend code
cd frontend
npm install

# Run tests
npm test

# Build for production
npm run build

# Deploy updates
fly deploy -a divemap

Configuration Management

Environment Variables

# List current secrets
fly secrets list -a divemap-backend

# Update secrets
fly secrets set NEW_SECRET=value -a divemap-backend

# Remove secrets
fly secrets unset OLD_SECRET -a divemap-backend

Configuration Files

# Update configuration
fly deploy -a divemap-backend

# Check configuration
fly ssh console -a divemap-backend -C "cat /app/config.py"

Infrastructure Maintenance

Container Management

Container Health

# Check container status
fly status

# Restart containers
fly restart -a divemap
fly restart -a divemap-backend
fly restart -a divemap-db

Resource Monitoring

# Check resource usage
fly status

# Monitor memory usage
fly ssh console -C "free -h"

# Check disk space
fly ssh console -C "df -h"

Network Maintenance

SSL Certificate Management

# Check SSL certificate status
curl -I https://divemap.fly.dev/

# Verify certificate expiration
openssl s_client -connect divemap.fly.dev:443 -servername divemap.fly.dev

DNS Management

# Check DNS resolution
nslookup divemap.fly.dev

# Verify DNS propagation
dig divemap.fly.dev

Security Maintenance

Vulnerability Scanning

Dependency Scanning

# Scan Python dependencies
cd backend
source divemap_venv/bin/activate
safety check

# Scan Node.js dependencies
cd frontend
npm audit

Application Scanning

# Check for common vulnerabilities
curl -X POST https://divemap-backend.fly.dev/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"wrong"}'

Access Control

User Management

# Review user accounts
fly ssh console -a divemap-backend -C "mysql -u divemap_user -p divemap -e
'SELECT username, email, role, is_active FROM users'"

# Disable inactive users
fly ssh console -a divemap-backend -C "mysql -u divemap_user -p divemap -e
'UPDATE users SET is_active = 0 WHERE last_login < DATE_SUB(NOW(), INTERVAL 90
DAY)'"

Authentication Review

# Check failed login attempts
fly logs -n -a divemap-backend | grep -i "failed login"

# Review authentication logs
fly logs -n -a divemap-backend | grep -i "unauthorized"

Monitoring and Alerts

Health Monitoring

Application Health

# Monitor application health
curl -f https://divemap.fly.dev/health

# Check API endpoints
curl -f https://divemap-backend.fly.dev/health

# Monitor response times
curl -w "@curl-format.txt" -o /dev/null -s https://divemap.fly.dev/

Database Health

# Check database connectivity
fly ssh console -C "mysql -u divemap_user -p divemap -e 'SELECT 1'"

# Monitor database performance
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SHOW PROCESSLIST'"

Alert Configuration

Error Alerts

# Monitor error rates
fly logs -n | grep -i error | wc -l

# Check for critical errors
fly logs -n | grep -i "critical\|fatal\|panic"

Performance Alerts

# Monitor response times
curl -w "Time: %{time_total}s\n" -o /dev/null -s https://divemap.fly.dev/

# Check resource usage
fly status

Troubleshooting

Quick Diagnosis

Health Checks

# Check application health
curl -f https://divemap.fly.dev/health
curl -f https://divemap-backend.fly.dev/health

# Check service status
fly status

# Check database connectivity
fly ssh console -C "mysql -u divemap_user -p divemap -e 'SELECT 1'"

Common Issues

1. Application Not Responding

# Check logs
fly logs -n -a divemap

# Restart application
fly restart -a divemap

# Check resources
fly status

2. Database Connection Issues

# Check database status
fly status -a divemap-db

# Test connectivity
fly ssh console -C "mysql -u divemap_user -p divemap -e 'SELECT 1'"

# Run migrations
fly ssh console -a divemap-backend -C "python run_migrations.py"

3. Authentication Issues

# Check authentication logs
fly logs -n -a divemap-backend | grep -i auth

# Test authentication (using PAT)
curl -H "Authorization: Bearer dm_pat_your_token_here" https://divemap-backend.fly.dev/api/v1/auth/me

4. Migration Failures

# Check migration status
fly ssh console -a divemap-backend -C "alembic current"

# Run migrations
fly ssh console -a divemap-backend -C "python run_migrations.py"

# Reset migration state
fly ssh console -a divemap-backend -C "alembic stamp head"

5. Performance Issues

# Check database performance
fly ssh console -a divemap-db -C "mysql -u root -p -e 'SHOW PROCESSLIST'"

# Check slow queries
fly ssh console -a divemap-db -C "tail -f /var/log/mysql/slow.log"

# Monitor resource usage
fly status

Debug Procedures

Enable Debug Logging

# Enable debug mode
fly secrets set DEBUG=true -a divemap-backend

# Check debug logs
fly logs -n -a divemap-backend | grep -i debug

Manual Testing

# Test API endpoints
curl -X GET https://divemap-backend.fly.dev/dive-sites
curl -X GET https://divemap-backend.fly.dev/health

# Test frontend
curl -I https://divemap.fly.dev/

Import Scripts Maintenance

Dive Site Import Scripts

The application includes enhanced import scripts for managing dive site data with smart conflict resolution.

import_subsurface_divesite.py

  • Purpose: Import dive sites from text files with preference for updating existing sites
  • Strategy: Prevents duplicate creation by checking similarity and proximity
  • Conflict Resolution: Offers interactive, batch, and merge file modes

Maintenance Tasks:

# Verify import script functionality
cd utils
python import_subsurface_divesite.py --dry-run

# Test with sample data
python import_subsurface_divesite.py -f --skip-all

# Create merge files for review
python import_subsurface_divesite.py --create-merge-all

Key Features for Maintenance:

  • Smart Matching: Uses similarity algorithms to detect existing sites
  • Proximity Checking: 200m threshold to prevent nearby duplicates
  • Selective Updates: Preserves existing data not in import files
  • Batch Processing: Multiple modes for different import scenarios
  • Merge Files: Manual review capability for complex updates

Update Behavior:

  • Always Updated: name, description, latitude, longitude
  • Preserved: address, access_instructions, difficulty_level, marine_life, safety_information, aliases, country, region
  • Selective: Only changes fields present in import data

import_kml_dive_sites.py

  • Purpose: Import dive sites from KML files with automatic tag assignment
  • Maintenance: Verify icon-to-tag mapping accuracy

Maintenance Tasks:

# Test KML import functionality
python import_kml_dive_sites.py sample_dive_sites.kml

# Verify tag assignments
mysql -u divemap_user -p divemap -e "SELECT name, GROUP_CONCAT(tag_name) FROM
dive_sites ds JOIN dive_site_tags dst ON ds.id = dst.dive_site_id JOIN
available_tags at ON dst.tag_id = at.id GROUP BY ds.id;"

Import Script Best Practices

  1. Always backup database before large imports
  2. Use dry-run mode to preview changes
  3. Review merge files before applying complex updates
  4. Test with small datasets first
  5. Monitor import logs for errors
  6. Verify data integrity after imports

Recovery Procedures

Database Recovery

# Restore from backup
fly ssh console -a divemap-db -C "mysql -u root -p divemap <
/backups/divemap_backup.sql"

# Verify restoration
fly ssh console -a divemap-db -C "mysql -u divemap_user -p divemap -e 'SELECT
COUNT(*) FROM dive_sites'"

Application Recovery

# Restart all services
fly restart -a divemap
fly restart -a divemap-backend
fly restart -a divemap-db

# Verify recovery
curl -f https://divemap.fly.dev/health

Maintenance Checklist

Daily

  • Health checks
  • Backup verification
  • Log review
  • Error monitoring

Weekly

  • Security updates
  • Performance analysis
  • Log analysis
  • Dependency checks

Monthly

  • Dependency updates
  • Database optimization
  • Security review
  • Infrastructure review

Quarterly

  • Comprehensive security audit
  • Performance optimization
  • Backup strategy review
  • Disaster recovery testing

Database Export/Import

For detailed information about exporting and importing diving centers and dive sites data between local development and fly.io production databases, see:

This includes:

  • Full backup procedures
  • Selective table export/import
  • Data integrity maintenance
  • Troubleshooting and rollback procedures

Support

For maintenance issues:

  1. Check this troubleshooting guide
  2. Review logs for specific errors
  3. Test manual procedures
  4. Contact development team
  5. Escalate to infrastructure team

Conclusion

Regular maintenance ensures the Divemap application remains reliable, secure, and performant. Following these procedures helps prevent issues and maintain high availability.