mev-beta/DEV_ENVIRONMENT.md

MEV Bot Development Environment

This guide explains how to use the development environment with branch selection and podman-in-podman support.

Quick Start

Start Development Environment

# Start with default branch (master-dev)
./scripts/dev-env.sh start

# Start with specific branch
./scripts/dev-env.sh start fix-critical-arbitrage-bugs

# Start with master branch
./scripts/dev-env.sh start master

Switch Branches

# Switch to a different branch (stops current, checks out, rebuilds)
./scripts/dev-env.sh switch feat-new-feature

# List available branches
./scripts/dev-env.sh branches

View Logs

# Follow logs
./scripts/dev-env.sh logs -f

# Show last 100 lines
./scripts/dev-env.sh logs --tail 100

Access Container Shell

# Open interactive shell in running container
./scripts/dev-env.sh shell

Stop/Restart

# Stop development environment
./scripts/dev-env.sh stop

# Restart with same branch
./scripts/dev-env.sh restart

# Restart with different branch
./scripts/dev-env.sh restart master

Rebuild

# Full rebuild (no cache) with current branch
./scripts/dev-env.sh rebuild

# Full rebuild with specific branch
./scripts/dev-env.sh rebuild master-dev

Architecture

Files

• Dockerfile.dev - Development dockerfile with branch selection support
• docker-compose.dev.yml - Development compose configuration
• scripts/dev-env.sh - Development environment management script

Features

1. Branch Selection: Build and run from any git branch
2. Podman-in-Podman: Container can run podman commands (privileged mode)
3. Live Logs: Persistent log directory mounted from host
4. Hot Reload: Source code mounted for development (optional)
5. Resource Management: Configurable CPU and memory limits

Environment Variables

Set these in .env or export before running:

# Branch to build from
export GIT_BRANCH=master-dev

# Logging level
export LOG_LEVEL=debug

# Enable metrics
export METRICS_ENABLED=true

# RPC endpoint
export ARBITRUM_RPC_ENDPOINT=https://arb1.arbitrum.io/rpc

Podman-in-Podman Support

The development environment supports running podman inside the container:

# Access container shell
./scripts/dev-env.sh shell

# Inside container, you can use podman
podman ps
podman images
podman run ...

Requirements

• Container runs in privileged mode
• Podman socket mounted from host: /run/podman/podman.sock
• Persistent storage volume: podman-storage

Development Workflow

Feature Development

# 1. Create feature branch
git checkout -b feat-my-feature

# 2. Start development environment with your branch
./scripts/dev-env.sh start feat-my-feature

# 3. Make changes in your local files

# 4. Rebuild to test changes
./scripts/dev-env.sh rebuild feat-my-feature

# 5. View logs to verify
./scripts/dev-env.sh logs -f

# 6. When done, stop environment
./scripts/dev-env.sh stop

Testing Different Branches

# Test fix branch
./scripts/dev-env.sh switch fix-critical-arbitrage-bugs

# Test feature branch
./scripts/dev-env.sh switch feat-podman-compose-support

# Go back to master-dev
./scripts/dev-env.sh switch master-dev

Debugging

# Start with debug logging
export LOG_LEVEL=debug
./scripts/dev-env.sh start

# Access container for inspection
./scripts/dev-env.sh shell

# Inside container:
ps aux                          # Check processes
cat /app/config/config.yaml     # View config
ls -la /app                     # List files

Comparison: Development vs Production

Feature	Development (dev-env.sh)	Production (deploy-production-docker.sh)
Branch Selection	✅ Yes (any branch)	✅ Yes (defaults to master)
Dockerfile	Dockerfile.dev	Dockerfile
Compose File	docker-compose.dev.yml	docker-compose.yml
Privileged Mode	✅ Yes (for podman-in-podman)	❌ No
Resource Limits	Higher (4 CPU, 4GB RAM)	Lower (2 CPU, 2GB RAM)
Restart Policy	unless-stopped	always
Container Name	mev-bot-dev-{branch}	mev-bot-production
Source Mount	✅ Yes (optional)	❌ No
Auto-start on Boot	❌ No	✅ Yes (via systemd)

Troubleshooting

Container Won't Start

# Check status
./scripts/dev-env.sh status

# View logs
./scripts/dev-env.sh logs

# Rebuild from scratch
./scripts/dev-env.sh clean
./scripts/dev-env.sh rebuild

Branch Doesn't Exist

# List available branches
./scripts/dev-env.sh branches

# Update branch list
git fetch --all
./scripts/dev-env.sh branches

Podman Socket Not Available

# Check if podman socket is running
systemctl --user status podman.socket

# Start podman socket
systemctl --user start podman.socket

Out of Disk Space

# Clean old images and containers
./scripts/dev-env.sh clean

# Prune podman system
podman system prune -a

Advanced Usage

Custom Configuration

Create a .env.dev file for development-specific settings:

# .env.dev
GIT_BRANCH=master-dev
LOG_LEVEL=debug
METRICS_ENABLED=true
METRICS_PORT=9090
PORT=8080

Load it before starting:

set -a && source .env.dev && set +a
./scripts/dev-env.sh start

Manual Podman Commands

# Use docker-compose directly
export GIT_BRANCH=feat-my-branch
podman-compose -f docker-compose.dev.yml build
podman-compose -f docker-compose.dev.yml up -d

# Or use single command
GIT_BRANCH=feat-my-branch podman-compose -f docker-compose.dev.yml up -d --build

Performance Monitoring

# Access metrics endpoint (if enabled)
curl http://localhost:9090/metrics

# View resource usage
podman stats

Best Practices

1. Use feature branches for development, not master
2. Test in dev environment before merging to master-dev
3. Rebuild after git pull to ensure latest code
4. Monitor logs during development with -f flag
5. Clean regularly to free up disk space
6. Use specific branches instead of relying on defaults

Related Documentation

• DEPLOYMENT.md - Production deployment guide
• CLAUDE.md - Project overview and guidelines
• docker-compose.dev.yml - Development compose configuration
• Dockerfile.dev - Development dockerfile