How to Resolve Port Conflicts When Running Multiple App Containers in InternetIncome

The internetIncome.sh script automatically resolves port conflicts by detecting occupied ports with nc and incrementing the entire port range until it finds a free block, while also supporting manual overrides via environment variables.

When running the engageub/internetincome automation framework, multiple Docker containers for services like Mysterium, Ebesucher, and Adnade attempt to bind to host ports simultaneously. The script implements a dynamic port assignment mechanism to prevent collisions and ensure all services start without manual intervention.

Understanding the Port Assignment Mechanism

The script defines default starting ports for each service that requires a web UI or VNC interface. These values are hardcoded near the beginning of internetIncome.sh (lines 67-71):

# Mysterium and ebesucher first port

mysterium_first_port=2000   # ← default for Mysterium UI

ebesucher_first_port=3000   # ← default for Ebesucher UI

adnade_first_port=4000      # ← default for Adnade UI

Each service increments from these base values based on the number of instances configured. When the script launches a container, it maps the assigned host port to the container's internal service port using the -p flag.

Automatic Port Conflict Resolution

To prevent binding failures, the script includes a check_open_ports function (lines 88-115) that validates availability before assignment. The function uses nc (netcat) to test each port in the calculated range:

check_open_ports() {
    local first_port=$1
    local num_ports=$2
    ...
    for port in $port_range; do
        nc -z localhost $port > /dev/null 2>&1
        if [ $? -eq 0 ]; then
            open_ports=$((open_ports+1))
        fi
    done
    ...
}

If the function detects any occupied ports, it shifts the entire range forward by the number of required ports and repeats the check recursively until it locates a free block. The final available starting port is returned and used in the Docker run command:

# Example from lines 165-176 for Mysterium

if [[ $MYSTERIUM = true ]]; then
    mysterium_first_port=$(check_open_ports $mysterium_first_port 1)
    if ! expr "$mysterium_first_port" : '[[:digit:]]*$' >/dev/null; then
        echo -e "${RED}Problem assigning port $mysterium_first_port ..${NOCOLOUR}"
        exit 1
    fi
    myst_port="-p $mysterium_first_port:4449 "
    sudo docker run ... $myst_port mysteriumnetwork/myst:latest ...
fi

Manual Port Configuration

For environments requiring specific port assignments, you can override the auto-detection by exporting environment variables before invoking the script. While the base script uses hardcoded defaults, you can modify the logic or set custom variables that take precedence:

# Export custom ports before running the script

export MYSTERIUM_PORT=2100
export EBESUCHER_PORT=3100
export ADNADE_PORT=4100

# Then invoke the script

sudo bash internetIncome.sh --start

To implement this permanently, modify the port assignment blocks in internetIncome.sh (around lines 165-176) to check for the environment variable first:

if [[ -n "$MYSTERIUM_PORT" ]]; then
    mysterium_first_port=$MYSTERIUM_PORT
else
    mysterium_first_port=$(check_open_ports $mysterium_first_port 1)
fi

Troubleshooting Persistent Port Conflicts

If the script aborts with "Problem assigning port" or containers fail to start, verify the following common scenarios:

• Stale containers from previous runs: Previous instances may still hold ports. Run sudo bash internetIncome.sh --delete to remove all containers and free bindings.
• External processes using default ports: System services or other applications may occupy ports 2000-4000. Use sudo lsof -i :<port> to identify and terminate conflicting processes.
• Multiple script instances: Running several copies of internetIncome.sh simultaneously causes race conditions. Ensure only one instance executes at a time.
• Insufficient port range: If running many instances, the default ranges may exhaust available ports. Increase the starting port values in the script or use the manual override method described above.

Summary

• Automatic detection: The check_open_ports function in internetIncome.sh scans for occupied ports using nc and dynamically shifts the service port ranges until finding available blocks.
• Default ranges: Mysterium starts at 2000, Ebesucher at 3000, and Adnade at 4000, with each service incrementing based on instance count.
• Manual override: Set MYSTERIUM_PORT, EBESUCHER_PORT, or ADNADE_PORT environment variables to bypass auto-assignment and force specific bindings.
• Cleanup: Use --delete to remove stale containers and free ports, or manually kill processes occupying the target ranges.

Frequently Asked Questions

What is the default port range for Mysterium in InternetIncome?

By default, Mysterium uses port 2000 as its starting host port, mapping to internal port 4449 inside the container. If port 2000 is occupied, the script automatically increments to 2001, 2002, etc., until it finds an available port. This logic is defined in internetIncome.sh at lines 67-71 and 165-176.

How does the script detect if a port is already in use?

The script uses the nc (netcat) command within the check_open_ports function (lines 88-115) to test connectivity to localhost on each candidate port. If nc -z localhost $port returns exit code 0, the port is marked as open (occupied). The function counts occupied ports in the range and, if any are found, recursively checks the next block of ports shifted by the number of required instances.

Can I manually set specific ports instead of using auto-assignment?

Yes, though it requires minor script modification. You can export environment variables such as MYSTERIUM_PORT, EBESUCHER_PORT, or ADNADE_PORT before running the script, then edit internetIncome.sh to check these variables before calling check_open_ports. For example, add a conditional block that sets mysterium_first_port=$MYSTERIUM_PORT if the variable is non-empty, otherwise use the auto-detection routine.

What should I do if the script fails with a port assignment error?

First, run sudo bash internetIncome.sh --delete to remove any stale containers that may be holding ports from previous runs. Next, check for external processes using the default ports (2000, 3000, 4000) with sudo lsof -i :<port> and terminate them if necessary. Ensure you are not running multiple instances of the script simultaneously, as this causes race conditions. If conflicts persist, modify the starting port values in internetIncome.sh or use environment variable overrides to select a different port range.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}