Skip to main content
Version: Next

Network Configuration

This guide covers basic network configuration for Merobox, including port management and network settings.

Port Configuration​

Merobox provides basic port configuration for Calimero nodes:

Basic Port Settings​

Configure ports in workflow files:

# workflow.yml
nodes:
  chain_id: testnet-1
  count: 2
  image: ghcr.io/calimero-network/merod:edge
  prefix: calimero-node
  base_port: 2428 # Base P2P port (optional)
  base_rpc_port: 2528 # Base RPC port (optional)

CLI Port Configuration​

Set ports using command-line flags:

# Custom base ports
merobox run --count 2 --base-port 2428 --base-rpc-port 2528

# Different port ranges
merobox run --count 3 --base-port 3000 --base-rpc-port 4000

Automatic Port Detection​

Merobox automatically detects available ports:

  • P2P Ports: Starting from 2428, increments by 1 for each node
  • RPC Ports: Starting from 2528, increments by 1 for each node
  • Conflict Resolution: Automatically finds next available ports

Environment Variables​

Configure network settings using environment variables:

Network Configuration​

# Network configuration is done through CLI flags
# merobox run --base-port 3000 --base-rpc-port 4000

Advanced Network Settings​

# Advanced network configuration is done through Docker
# Create custom Docker networks if needed
docker network create calimero-custom

Docker Networks​

Merobox uses Docker's default networking:

Default Network Behavior​

  • Bridge Network: Merobox uses Docker's default bridge network
  • Automatic Management: Networks are created and managed automatically
  • Node Communication: Nodes can communicate with each other by default

Network Management​

# List Docker networks
docker network ls

# Inspect Merobox networks
docker network inspect bridge

# Check node network connectivity
docker exec calimero-node-1 ping calimero-node-2

Troubleshooting​

Common Network Issues​

Check network connectivity and port availability:

# Check port binding
netstat -tulpn | grep -E "(2428|2528)"

# Test connectivity between nodes
docker exec calimero-node-1 ping calimero-node-2

# Check Docker networks
docker network ls
docker network inspect bridge

# Find processes using ports
lsof -ti:2528

Port Conflicts​

If ports are already in use:

# Kill process using port
lsof -ti:2528 | xargs kill

# Or use different ports
merobox run --base-rpc-port 3000

# Check all ports
netstat -tulpn | grep -E "(2428|2528)"

Network Debugging​

Enable debug logging for troubleshooting:

# Enable debug logging
export LOG_LEVEL=DEBUG

# Run with verbose output
merobox run --count 2 --verbose

# Check node logs
merobox logs calimero-node-1

Best Practices​

Port Management​

  1. Use Default Ports: Stick to default ports (2428, 2528) when possible
  2. Avoid Conflicts: Check for port conflicts before starting nodes
  3. Document Ports: Keep track of custom port configurations
  4. Test Connectivity: Verify node communication after configuration changes

Network Configuration​

  1. Environment Variables: Use environment variables for consistent configuration
  2. Port Ranges: Use appropriate port ranges for different environments
  3. DNS Settings: Configure DNS for better name resolution
  4. Network Isolation: Use network isolation for security when needed

Troubleshooting​

  1. Check Logs: Always check node logs first when issues occur
  2. Verify Ports: Ensure ports are available and not conflicting
  3. Test Connectivity: Use ping and other tools to test connectivity
  4. Docker Networks: Check Docker network status and configuration

Next Steps​

Now that you understand basic network configuration:

Was this page helpful?
Need some help? Check Support page