​
Troubleshooting Guide: Docker Port Conflicts

Port conflicts are a common issue when deploying Docker containers, especially in complex setups like R2R. This guide will help you identify, diagnose, and resolve port conflicts in your Docker environment.

​
Understanding Port Conflicts

A port conflict occurs when two processes attempt to use the same network port. In Docker, this typically happens when:

  1. A container tries to bind to a port already in use by the host system.
  2. Multiple containers attempt to use the same port.
  3. A container’s port mapping conflicts with another container or host process.

​
Identifying Port Conflicts

Signs of a port conflict include:

  • Error messages during container startup mentioning “port is already allocated” or “address already in use”.
  • Services failing to start or be accessible.
  • Unexpected behavior in applications that rely on specific ports.

​
Steps to Diagnose and Resolve Port Conflicts

​
1. Check for Used Ports

First, identify which ports are already in use on your system:

sudo lsof -i -P -n | grep LISTEN

or

netstat -tuln

​
2. Review Docker Compose File

Examine your docker-compose.yml file for port mappings:

services:
  myservice:
    ports:
      - "8080:80"  # Host port 8080 maps to container port 80

​
3. Modify Port Mappings

If you identify a conflict, you can:

a. Change the host port in your Docker Compose file:

services:
  myservice:
    ports:
      - "8081:80"  # Changed from 8080 to 8081

b. Use automatic port assignment:

services:
  myservice:
    ports:
      - "80"  # Docker will assign a random available host port

​
4. Stop Conflicting Services

If a host service is using the required port:

sudo service conflicting_service stop

​
5. Release Docker Resources

Sometimes, stopping and removing all Docker containers and networks can help:

docker-compose down
docker system prune

​
6. Check for Docker Network Conflicts

Ensure your Docker networks don’t have overlapping subnets:

docker network ls
docker network inspect network_name

​
7. Use Network Host Mode (Caution)

As a last resort, you can use host network mode, but this bypasses Docker’s network isolation:

services:
  myservice:
    network_mode: "host"

​
8. Debugging with Docker Logs

Check container logs for more detailed error messages:

docker-compose logs service_name

​
Specific R2R Port Conflict Scenarios

​
R2R API Server Conflict

If the R2R API server (default port 7272) is conflicting:

  1. Check if any other service is using port 7272:

    sudo lsof -i :7272

  2. Modify the R2R service in your docker-compose.yml:

    services:
  r2r:
    ports:
      - "7273:7272"  # Changed host port to 7273

  3. Update your environment variables:

    PORT=7273

​
Hatchet Engine Conflict

If the Hatchet engine (default port 7077) is conflicting:

  1. Check for conflicts:

    sudo lsof -i :7077

  2. Modify the Hatchet engine service:

    services:
  hatchet-engine:
    ports:
      - "7078:7077"

  3. Update the SERVER_GRPC_BROADCAST_ADDRESS environment variable for the Hatchet engine service.

​
Preventing Future Conflicts

  1. Use environment variables for port numbers in your Docker Compose file.
  2. Document the ports used by each service in your project.
  3. Consider using tools like Traefik or Nginx as reverse proxies to manage port allocation dynamically.

By following this guide, you should be able to identify and resolve most port conflicts in your Docker and R2R setup. Remember, after making changes to your Docker Compose file or configuration, you’ll need to rebuild and restart your services:

docker-compose down
docker-compose up --build

If problems persist, check the R2R documentation or seek help from the community support channels.