How to Resolve Port Conflict Errors in Umbrel OS and Docker

✨ Quick Answer

The port binding error (bind: address already in use or port already allocated) when attempting to start a custom container in Umbrel OS occurs because the platform's internal web proxy (based on Nginx or Traefik) has already reserved ports 80 and 443 to manage the app store interface and secure dashboard access.

Quick Diagnostics

Cause

Port 80 or 443 required by Umbrel app occupied by another service

Solution

Modify port mapping in App's docker-compose.yml file

Cause

Local Nginx or Apache process blocking host ports

Solution

Identify and stop conflicting service: sudo systemctl stop nginx

The port binding error (bind: address already in use or port already allocated) when attempting to start a custom container in Umbrel OS occurs because the platform's internal web proxy (based on Nginx or Traefik) has already reserved ports 80 and 443 to manage the app store interface and secure dashboard access.

Step-by-Step Solution

1. 1

   Step 1: Identify which process or container is using the port

   Before modifying any compose files, connect to your Umbrel via SSH and identify precisely which service is binding to the target port:

   BASH Copy

   # Locate processes listening on the conflicting port (e.g., port 80)
   sudo lsof -i :80
   
   # List active Docker container port mappings
   docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}"
   

2. 2

   Step 2: Update port mapping in your docker-compose.yml file

   Do not attempt to kill or remove processes belonging to Umbrel's native dashboard. Instead, modify the port mapping of the container you want to deploy, changing its host-facing port to an unallocated one (e.g., change 80:80 to 8085:80):

   YAML Copy

   services:
     app-custom:
       image: nginx:alpine
       ports:
         # Map free host port 8085 to container port 80
         - "8085:80"
   

3. 3

   Step 3: Recreate and start the container

   Apply the configuration changes by recreating the container:

   BASH Copy

   # Bring the container stack down and recreate it in detached mode
   docker compose down && docker compose up -d