60c3336725
fix(docker): update GeoLite2-Country.mmdb checksum + automation Fixes critical Docker build failure caused by upstream GeoLite2 database update without corresponding Dockerfile checksum update. **Root Cause:** - GeoLite2-Country.mmdb file updated upstream - Dockerfile still referenced old SHA256 checksum - Build aborted at checksum verification (line 352) - Cascade "blob not found" errors for all COPY commands **Changes:** - Update Dockerfile ARG GEOLITE2_COUNTRY_SHA256 to current value - Add automated weekly checksum update workflow (.github/workflows/update-geolite2.yml) - Implement error handling: retry logic, format validation, failure notifications - Document rollback decision matrix with 10 failure scenarios - Create comprehensive maintenance guide (docs/maintenance/geolite2-checksum-update.md) - Update CHANGELOG.md and README.md with maintenance references **Verification:** - Checksum verified against current upstream file: 436135ee... - Pre-commit hooks: PASSED (EOF/whitespace auto-fixed) - Trivy security scan: PASSED (no critical/high issues) - Dockerfile syntax: VALID - GitHub Actions YAML: VALID - No hardcoded secrets or injection vulnerabilities **Automation Features:** - Weekly scheduled checks (Monday 2 AM UTC) - Auto-PR creation when checksum changes - GitHub issue creation on workflow failure - Comprehensive error handling and retry logic **Impact:** - Unblocks all CI/CD Docker image builds - Enables publishing to GHCR/Docker Hub - Prevents future checksum failures via automation - Zero application code changes (no regression risk) **Documentation:** - Implementation plan: docs/plans/geolite2_checksum_fix_spec.md - QA report: docs/reports/qa_geolite2_checksum_fix.md - Maintenance guide: docs/maintenance/geolite2-checksum-update.md **Supervisor Recommendations Implemented:** - #1: Checksum freshness verification before update - #3: Rollback decision criteria (10 scenarios) - #4: Automated workflow error handling Resolves: https://github.com/Wikid82/Charon/actions/runs/21584236523/job/62188372617 COMMIT_MESSAGE_END
Maintenance Documentation
This directory contains operational maintenance guides for keeping Charon running smoothly.
Available Guides
GeoLite2 Database Checksum Update
When to use: Docker build fails with GeoLite2-Country.mmdb checksum mismatch
Topics covered:
- Automated weekly checksum verification workflow
- Manual checksum update procedures (5 minutes)
- Verification script for checking upstream changes
- Troubleshooting common checksum issues
- Alternative sources if upstream mirrors are unavailable
Quick fix:
# Download and update checksum automatically
NEW_CHECKSUM=$(curl -fsSL "https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-Country.mmdb" | sha256sum | cut -d' ' -f1)
sed -i "s/ARG GEOLITE2_COUNTRY_SHA256=.*/ARG GEOLITE2_COUNTRY_SHA256=${NEW_CHECKSUM}/" Dockerfile
docker build --no-cache -t test .
Contributing
Found a maintenance issue not covered here? Please:
- Create an issue describing the problem
- Document the solution in a new guide
- Update this index with a link to your guide
Format:
### [Guide Title](filename.md)
**When to use:** Brief description of when this guide applies
**Topics covered:**
- List key topics
**Quick command:** (if applicable)
Related Documentation
- Troubleshooting — Common runtime issues and fixes
- Runbooks — Emergency procedures and incident response
- Configuration — Setup and configuration guides
- Development — Developer environment and workflows
Last Updated: February 2, 2026