Skip to content

Use named volumes for data persistence and add AOF repair - #261

Merged
maximusunc merged 2 commits into
develfrom
claude/vibrant-pascal-9sjtkd
Nov 13, 2026
Merged

maximusunc merged 2 commits into
develfrom
claude/vibrant-pascal-9sjtkd

Conversation

@maximusunc

Copy link
Copy Markdown
Collaborator

Summary

This PR improves data durability and reliability by switching from bind mounts to named volumes for persistent data storage, and adds automatic repair of corrupted Redis append-only files (AOF) at startup.

Key Changes

  • Switch to named volumes: Replaced bind mounts (./pgdata, ./data, ./data/redisinsight) with named Docker volumes (db_data, broker_data, broker_insight_data) for Postgres, Redis, and RedisInsight. This ensures data durability on Docker Desktop where bind mounts don't guarantee fsync durability through the host file-sharing layer.

  • Add Redis AOF auto-repair: Implemented automatic detection and repair of corrupted Redis append-only files in shepherd_broker/entrypoint.sh. When REDIS_AOF_AUTOFIX=yes (enabled by default), the broker checks the AOF manifest at startup and truncates damaged files at the first bad command, preventing restart loops. Damaged files are backed up to appendonlydir.damaged for inspection.

  • Add REDIS_AOF_AUTOFIX environment variable: New optional configuration in compose.yml (defaults to yes) to control AOF auto-repair behavior.

  • Update documentation: Added comprehensive section to README explaining the data volume changes, AOF repair behavior, and how to reset volumes.

Implementation Details

  • The AOF repair logic uses redis-check-aof to validate the manifest and redis-check-aof --fix to repair it, with proper error handling and user guidance if repair fails.
  • Damaged AOF files are preserved in a backup directory for inspection rather than deleted.
  • The change is backward compatible: existing deployments can continue using bind mounts by setting REDIS_AOF_AUTOFIX=no if preferred.
  • All three services now use named volumes defined in the volumes: section at the end of compose.yml.

On Docker Desktop the ./data bind mount goes through the host file-sharing
layer, whose fsync doesn't make the AOF durable: an unclean stop left the
incremental AOF with a garbage tail, and Redis restart-looped on "Bad file
format reading the append only file". RedisInsight's ./data/redisinsight was
nested inside that mount, so after ./data was deleted Docker had to create
both host directories at once and failed with "error while creating mount
source path ...: file exists".

Redis and RedisInsight now use their own named volumes, and with
REDIS_AOF_AUTOFIX=yes (the compose default) the broker checks the AOF before
starting and truncates it at the first bad command, keeping the damaged files
in /data/appendonlydir.damaged. It stays off by default in the image, since
the check reads the whole AOF on every start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S2yuRDKRKriR3NMgBXzQ7s
The ./pgdata bind mount had the same problem as the broker's ./data on Docker
Desktop: the host file-sharing layer doesn't make Postgres's WAL durable, so
an unclean stop could corrupt the database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S2yuRDKRKriR3NMgBXzQ7s
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.69%. Comparing base (20feeb3) to head (08952ef).
⚠️ Report is 1 commits behind head on devel.
see 2 files with indirect coverage changes


Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0318504...08952ef. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@maximusunc
maximusunc merged commit 0235f95 into devel Nov 13, 2026
2 checks passed
@maximusunc
maximusunc deleted the claude/vibrant-pascal-9sjtkd branch November 13, 2026 18:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants