Standard Environment Pattern

A Standard Environment has two Redis instances: - Vault (Master): Password-protected, accepts writes - Operational (Slave): No password, read-only replica

Architecture

[MCP Server] --write--> [Vault:6XXX] --replicates--> [Operational:6XX1]
     ^                                                      |
     |__________________ read ______________________________|

Security Model

1. Vault requires password for ALL operations
2. Operational has no password (fast reads)
3. If Operational is wiped, Vault automatically refills it
4. If Vault is compromised, backups restore it

Port Convention

• Vault: 66X0 (even numbers)
• Operational: 66X1 (odd numbers)
• Examples: Track (6640/6641), Context (6620/6621), Session (6645/6646)

Container Setup

Both vault and operational run in Docker containers using FalkorDB image.

Vault Container

docker run -d \
  --name nexus3-{env}-vault \
  --restart unless-stopped \
  --network nexus-storage-network \
  -p {vault_port}:6379 \
  -v /data/nexus3/{env}/vault:/var/lib/falkordb/data \
  falkordb/falkordb:latest \
  redis-server --loadmodule /var/lib/falkordb/bin/falkordb.so

Operational Container

docker run -d \
  --name nexus3-{env}-operational \
  --restart unless-stopped \
  --network nexus-storage-network \
  -p {operational_port}:6379 \
  -v /data/nexus3/{env}/operational:/var/lib/falkordb/data \
  falkordb/falkordb:latest \
  redis-server --loadmodule /var/lib/falkordb/bin/falkordb.so

Setting Up Replication

CRITICAL LEARNINGS

1. FalkorDB containers do NOT load redis.conf on startup - they ignore it
2. Native Redis 6.x cannot replicate from Redis 8.x - RDB format version 12 incompatible
3. Both containers must be on same Docker network for name resolution
4. Replication must be configured at runtime after containers start

Step 1: Ensure Same Network

docker network connect nexus-storage-network nexus3-{env}-vault
docker network connect nexus-storage-network nexus3-{env}-operational

Step 2: Set Vault Password (Runtime)

FalkorDB doesn't read redis.conf, so set password at runtime:

redis-cli -p {vault_port} CONFIG SET requirepass {password}

Step 3: Configure Replication (Runtime)

redis-cli -p {operational_port} CONFIG SET masterauth {password}
redis-cli -p {operational_port} REPLICAOF nexus3-{env}-vault 6379

Step 4: Verify Replication

redis-cli -p {operational_port} INFO replication

Should show: - role:slave - master_link_status:up - master_host:nexus3-{env}-vault

Step 5: Test Write/Read

# Write to vault
redis-cli -p {vault_port} -a {password} SET test:key "value"

# Read from operational (should see the value)
redis-cli -p {operational_port} GET test:key

Making Replication Persistent

Runtime CONFIG commands don't survive container restarts. Solutions:

Option 1: Startup Script (Recommended for now)

Create a systemd service that runs after Docker and issues REPLICAOF commands.

Option 2: Docker Compose (Best for deployment)

Define startup commands in compose file with depends_on and healthchecks.

Option 3: Custom Docker Image

Extend FalkorDB image with custom entrypoint that loads redis.conf.

Directory Structure

/data/nexus3/{env}/
├── vault/
│   ├── redis.conf          # Password config (not auto-loaded)
│   ├── dump.rdb             # Data snapshot
│   └── appendonlydir/       # AOF persistence
└── operational/
    ├── redis.conf          # Replication config (not auto-loaded)
    └── dump.rdb            # Replicated data

Locker Integration

All vault passwords must be stored in Locker environment:

1. Create locker entry for environment credentials
2. MCP server uses credentials_helper to retrieve password
3. Never hardcode passwords in server files

Checklist for New Standard Environment

• [ ] Choose port pair (vault: 66X0, operational: 66X1)
• [ ] Create data directories: /data/nexus3/{env}/vault and /operational
• [ ] Create vault container on nexus-storage-network
• [ ] Create operational container on same network
• [ ] Set vault password at runtime
• [ ] Configure replication at runtime
• [ ] Verify replication is working
• [ ] Create locker entry for credentials
• [ ] Update credentials_helper with new environment
• [ ] Create/update MCP server to use new ports