Redis Manager

intent

manages the shared Redis Docker container for local dev environments. run this to start/stop Redis, check memory and key counts, inspect data by pattern, or selectively flush databases without losing everything. use it during dev setup before spinning up app instances, or when you need to wipe test data mid-session. Redis lives on the shared Docker network created by proxy-manager, so all app containers can hit it via hostname codai_redis on port 6379.

inputs

• docker, docker-compose: required binaries. must be installed and executable on PATH.
• proxy-manager: must run proxy-manager start first to create the nginx-proxy_net Docker network. redis-manager assumes this network exists as external.
• REDIS_CONTAINER env var: container name (default: codai_redis).
• REDIS_PASSWORD env var: AUTH password for redis-cli connections (default: redispass). change this on shared machines; default is insecure.
• REDIS_PORT env var: host port binding (default: 6380). maps to container's 6379. bound to 127.0.0.1 only.
• REDIS_MAXMEMORY env var: max memory before eviction policy kicks in (default: 256mb).
• CODAI_NETWORK env var: shared Docker network name (default: nginx-proxy_net).
• docker-compose.yml: file in redis-manager directory defines the Redis 7 Alpine container, volume, and network bindings.
• run.sh: bash script with lifecycle and data inspection commands.

procedure

1. ensure proxy-manager has run proxy-manager start. verify the nginx-proxy_net network exists: docker network ls | grep nginx-proxy_net.

2. (optional) set env vars if you want non-default values:

   export REDIS_CONTAINER=my_redis
   export REDIS_PASSWORD=strongpass123
   export REDIS_PORT=6381
   export REDIS_MAXMEMORY=512mb
   

3. start the container:

   cd redis-manager
   ./run.sh start
   

   output: container starts, joins network, persists data in named volume. confirm with docker ps | grep codai_redis.

4. (optional) wait for Redis to be ready:

   ./run.sh wait
   

   output: blocks until Redis replies PONG. exits 0 on success, non-zero on timeout (default 30s).

5. check status, key count, and memory:

   ./run.sh status
   

   output: prints container status (running/stopped), total key count, memory used, memory peak, eviction policy.

6. inspect keys by pattern (optional):

   ./run.sh list-keys
   ./run.sh list-keys "session:*"
   ./run.sh list-keys "cache:feature*"
   

   output: key list matching pattern (default: all keys via *). includes key count. warns if >1000 keys returned.

7. open interactive redis-cli (optional):

   ./run.sh cli
   

   output: interactive redis-cli prompt. already authenticated. type exit to return.

8. flush a single database (interactive):

   ./run.sh flush-db 0
   

   output: prompts "flush database 0? (yes/no)". only flushes database 0 if yes. uses single -n 0 redis-cli connection.

9. flush all databases (interactive):

   ./run.sh flush
   

   output: prompts "FLUSHALL will delete all data in all databases. confirm? (yes/no)". only runs FLUSHALL if yes.

10. stop the container when done:

    ./run.sh stop
    

    output: container stops. data persists in volume. container will auto-restart on Docker daemon restart due to restart: unless-stopped policy. if you want to delete persisted data, run docker compose down -v instead.

decision points

• if proxy-manager has not run yet: redis-manager start will fail with network not found error. always start proxy-manager first.
• if REDIS_PASSWORD is default (redispass) on a shared machine: script warns in status and list-keys output. set a strong password via env var before sharing the machine.
• if ./run.sh flush or ./run.sh flush-db <n> is called: script prompts for interactive confirmation. user types "yes" (exact match, case-insensitive allowed per implementation) to proceed. no confirmation = no flush.
• if ./run.sh flush-db <n> receives invalid DB number (non-integer, <0, >15): script rejects with error. Redis supports 16 databases (0-15) by default.
• if ./run.sh list-keys <pattern> returns >1000 keys: script warns that output is truncated and suggests a more specific pattern.
• if Redis container is stopped and user runs ./run.sh list-keys or ./run.sh flush-db: redis-cli fails to connect. script errors with "connection refused". user must run ./run.sh start first.
• if Docker daemon is down: all commands fail. user must restart Docker or docker-compose.
• if redis-cli connection times out (network latency, Redis hung): redis-cli waits ~5s then exits with timeout error. ./run.sh wait can retry.
• if host port 6380 (or REDIS_PORT) is already in use: docker compose up fails with bind error. user must change REDIS_PORT or kill the process using that port.
• if named volume is corrupted or inaccessible: container fails to start. user may need to run docker volume rm and recreate.

output contract

• ./run.sh start: exits 0 on success, container running. exits non-zero if network does not exist or port is in use. container name is value of REDIS_CONTAINER.
• ./run.sh stop: exits 0. container stopped, volume persists. data remains accessible on next start.
• ./run.sh status: stdout prints lines: "container status: running/stopped", "total keys: N", "memory usage: X MB", "memory peak: Y MB", "eviction policy: Z". if REDIS_PASSWORD is default, adds warning line.
• ./run.sh wait: blocks until redis-cli PING returns PONG. exits 0 on success, non-zero on timeout.
• ./run.sh list-keys [pattern]: stdout prints matching keys, one per line, followed by "total: N keys". if N >1000, adds warning. exits 0 if Redis is reachable, non-zero if not.
• ./run.sh flush-db : on confirm, exits 0 and prints "flushed database N". on deny, exits 0 and prints "flush cancelled". exits non-zero if N is invalid or Redis unreachable.
• ./run.sh flush: on confirm, exits 0 and prints "all databases flushed". on deny, exits 0 and prints "flush cancelled". exits non-zero if Redis unreachable.
• ./run.sh cli: spawns interactive redis-cli. exits when user types exit.

outcome signal

• start worked: run docker ps | grep codai_redis and see the container running. run ./run.sh status and see key count and memory. run ./run.sh wait and get PONG back.
• list-keys worked: you see a list of keys matching your pattern printed to stdout, no errors.
• flush-db worked: you confirm the prompt, see "flushed database N" message, then run ./run.sh list-keys and see fewer keys (or zero if database was previously populated).
• stop worked: run docker ps | grep codai_redis and see the container no longer running. run ./run.sh start again and confirm data is still there.
• connection failures indicate: Redis is not running (run ./run.sh start), network does not exist (run proxy-manager start), or Docker daemon is down.