> ## Documentation Index
> Fetch the complete documentation index at: https://r2r-patch-fix-ingestion.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Port conflicts

# 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:

```bash
sudo lsof -i -P -n | grep LISTEN
```

or

```bash
netstat -tuln
```

### 2. Review Docker Compose File

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

```yaml
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:

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

b. Use automatic port assignment:

```yaml
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:

```bash
sudo service conflicting_service stop
```

### 5. Release Docker Resources

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

```bash
docker-compose down
docker system prune
```

### 6. Check for Docker Network Conflicts

Ensure your Docker networks don't have overlapping subnets:

```bash
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:

```yaml
services:
  myservice:
    network_mode: "host"
```

### 8. Debugging with Docker Logs

Check container logs for more detailed error messages:

```bash
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:
   ```bash
   sudo lsof -i :7272
   ```

2. Modify the R2R service in your docker-compose.yml:
   ```yaml
   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:
   ```bash
   sudo lsof -i :7077
   ```

2. Modify the Hatchet engine service:
   ```yaml
   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:

```bash
docker-compose down
docker-compose up --build
```

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