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
58 lines
1.7 KiB
Markdown
58 lines
1.7 KiB
Markdown
# Maintenance Documentation
|
|
|
|
This directory contains operational maintenance guides for keeping Charon running smoothly.
|
|
|
|
## Available Guides
|
|
|
|
### [GeoLite2 Database Checksum Update](geolite2-checksum-update.md)
|
|
|
|
**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:**
|
|
```bash
|
|
# 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:
|
|
|
|
1. **Create an issue** describing the problem
|
|
2. **Document the solution** in a new guide
|
|
3. **Update this index** with a link to your guide
|
|
|
|
**Format:**
|
|
```markdown
|
|
### [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](../troubleshooting/)** — Common runtime issues and fixes
|
|
- **[Runbooks](../runbooks/)** — Emergency procedures and incident response
|
|
- **[Configuration](../configuration/)** — Setup and configuration guides
|
|
- **[Development](../development/)** — Developer environment and workflows
|
|
|
|
---
|
|
|
|
**Last Updated:** February 2, 2026
|