Cache Reaper

Automatically clean up stale custom domain mappings

The Cache Reaper is a Python maintenance utility that automatically cleans up stale custom domain mappings from Redis.

Overview

The Cache Reaper addresses situations where repositories are deleted, .pages files are removed, or domains are reconfigured—cases where Redis cache entries persist indefinitely.

Core Problems Solved

The tool handles cleanup of persistent storage entries (TTL=0) when:

  • Repositories are deleted
  • .pages files are removed
  • Custom domains change
  • Repositories become inaccessible

Installation Requirements

  • Python 3.7+
  • Redis access
  • Network connectivity to Forgejo
  • Optional: Forgejo API token for private repository verification

Dependencies install via: pip install -r requirements.txt

Configuration Methods

Command-line Arguments

  • --redis-host - Redis server hostname
  • --redis-port - Redis server port
  • --redis-password - Redis authentication password
  • --forgejo-host - Forgejo instance URL
  • --forgejo-token - Forgejo API token
  • --dry-run - Preview changes without modifications

Environment Variables

Provide an alternative configuration method:

  • REDIS_HOST
  • REDIS_PORT
  • REDIS_PASSWORD
  • FORGEJO_HOST
  • FORGEJO_TOKEN

Usage Workflow

Testing with Dry Run

Always test with --dry-run first to preview changes without making modifications:

python cache_reaper.py --dry-run

The dry-run mode displays which keys would be deleted and provides summary statistics.

Production Usage

Remove the --dry-run flag after verification:

python cache_reaper.py

Scheduling

  • High-traffic: Hourly
  • Medium-traffic: Every 6 hours
  • Low-traffic: Daily

Cron Scheduling

Example cron entry for hourly execution:

0 * * * * /usr/bin/python3 /path/to/cache_reaper.py

Systemd Timers

A modern alternative to cron for scheduling maintenance tasks.

Key Features

Deletion Scope

Removes:

  • Forward mappings
  • Reverse mappings
  • Traefik router configs

Exit Codes

  • 0: Success
  • 1: Fatal error
  • 2: Partial failure
  • 130: Interrupted

Logging

Output can be redirected to files with rotation management:

python cache_reaper.py >> /var/log/cache_reaper.log 2>&1

Security

  • Supports password authentication
  • Token management via environment variables
  • No credentials stored in code

Troubleshooting

Common Issues

Redis connection failures:

  • Verify Redis is running
  • Check hostname and port settings
  • Confirm authentication credentials

Forgejo API errors:

  • Verify API tokens
  • Check permissions
  • Ensure network connectivity

Module import errors:

  • Reinstall dependencies: pip install -r requirements.txt
  • Check Python version compatibility

Production Recommendations

  1. Use virtual environments - Isolate dependencies
  2. Implement log rotation - Prevent disk space issues
  3. Monitor execution metrics - Track cleanup statistics
  4. Maintain Redis backups - Before running cleanup
  5. Test on staging - Before production deployment

Example Commands

Basic Execution

python cache_reaper.py \
  --redis-host localhost \
  --redis-port 6379 \
  --forgejo-host https://git.example.com

With Authentication

python cache_reaper.py \
  --redis-host localhost \
  --redis-port 6379 \
  --redis-password secret \
  --forgejo-host https://git.example.com \
  --forgejo-token ghp_abcd1234

Dry Run Test

python cache_reaper.py --dry-run

Monitoring

Track cache reaper effectiveness by monitoring:

  • Number of keys cleaned per run
  • Execution time
  • Error rates
  • Redis memory usage trends