NEXUS 3.0 CONTAINERIZATION RESEARCH REPORT

Agent: Peter | Date: January 13, 2026

CURRENT ARCHITECTURE SUMMARY

• 36 running containers (all FalkorDB-based Redis environments)
• 19+ MCP servers in /opt/mcp-servers/ (~131MB)
• Data storage: ~82MB in /data/nexus3/ (grows with usage)
• Port range: 6610-6690 (vault=X0, operational=X1 pattern)
• Docker image: FalkorDB ~367MB (shared across all containers)

APPROACH 1: Docker-in-Docker (DinD)

How it works

Run a Docker daemon inside a container, then spawn Nexus containers inside that.

VERDICT: ❌ NOT RECOMMENDED

Cons: - Requires --privileged mode = major security risk - Performance overhead: double overlay filesystem = slower I/O - OverlayFS-on-OverlayFS causes instability - Storage driver issues at scale - Debugging is complex (inner containers invisible to host) - Not production-ready per Docker's own documentation

Pros: - Full isolation - Single "box" concept

APPROACH 2: Docker Compose Bundle (RECOMMENDED ✅)

How it works

Ship docker-compose.yml + .env + data tarball. Deploy with standard Docker Compose on target server.

VERDICT: ✅ BEST OPTION

Architecture:

nexus-deploy/
├── docker-compose.yml     # All 36 containers defined
├── .env                   # Vault passwords (generated)
├── scripts/
│   ├── generate-passwords.sh
│   ├── init-directories.sh
│   └── verify-replication.sh
└── README.md

Deployment on Margaheata:

git clone https://github.com/corlera/nexus-deploy.git /opt/nexus
cd /opt/nexus
./scripts/generate-passwords.sh > .env
./scripts/init-directories.sh
docker-compose up -d

Pros: - Native Docker - no nested complexity - Same performance as current setup - Modular profiles (core, full, media, etc.) - Easy backup/restore (tar the data directory) - Already documented in KB (node f92751c4)

Cons: - Requires Docker on target server - Not a "single file" but a simple folder - Must manually copy MCP servers separately

APPROACH 3: Podman Alternative

How it works

Use Podman instead of Docker - rootless, daemonless, more secure.

VERDICT: ⚠️ VIABLE BUT REQUIRES TESTING

Pros: - Rootless containers (no root daemon) - Better security model - Podman-compose supports Docker Compose files - No licensing concerns

Cons: - Not 100% Docker Compose compatible - Some networking features differ in rootless mode - Team familiarity with Docker is higher - Complex Compose files may need modifications

APPROACH 4: Kubernetes/K8s Pod

VERDICT: ❌ OVERKILL

Too complex for single-server deployment. K8s is for multi-node orchestration.

DISK SIZE REQUIREMENTS

Total for portable deployment: ~2-3GB including images and data

PORT MAPPING STRATEGY

Keep identical port mapping (6610-6690). The docker-compose.yml already maps internal 6379 to external 66XX ports. No changes needed for Margaheata - same ports work.

VOLUME/DATA STRATEGY

Option A: Fresh Deploy (Recommended for new client) - Generate new passwords - Create empty data directories - Start fresh

Option B: Clone Existing

# On source (cortex-nexus-master)
tar -czf nexus-data.tar.gz /data/nexus3/
scp nexus-data.tar.gz margaheata:/tmp/

# On target (margaheata)
tar -xzf /tmp/nexus-data.tar.gz -C /

FINAL RECOMMENDATION

Use Docker Compose Bundle (Approach 2)

1. Create nexus-deploy repo with:
2. docker-compose.yml (all environments with profiles)
3. Password generation scripts
4. Replication init service

5. Modular profiles for selective deployment

6. For Margaheata deployment:

7. Clone repo
8. Run setup scripts

9. docker-compose --profile core up -d (or --profile full)

10. MCP servers deployed separately:

11. Clone /opt/mcp-servers/
12. Configure Claude Code to use them

NOT Docker-in-Docker - security and performance issues make it unsuitable for production.

NEXT STEPS

1. Create nexus-deploy GitHub repo
2. Write complete docker-compose.yml with all 36 containers
3. Implement profile system (core vs full)
4. Document deployment process
5. Test on Margaheata