Port Conflict Fix

Port 8000 Was the Wrong Port

SGLang listens on port 30000 by default, but OpenWebUI’s config pointed to port 8000 in the environment section of its docker-compose.yml:

environment:
  OPENAI_API_BASE_URL: https://informatics.systems/knowledgebase/serv-u/port-conflicts-with-other-applications./v1

That address never answered. Running netstat confirmed port 8000 was in use:

netstat -tulnp | grep :8000
tcp   0   0 0.0.0.0:8000   0.0.0.0:*   LISTEN   1234/docker-proxy

The PID belonged to a WordPress container (version 5.9.3) that had been left running long after the shop migrated to Astro. Docker’s port mapping hid the collision until OpenWebUI tried to call SGLang. The container was using WordPress 6.4.3 with WooCommerce 8.3.0, both running on PHP 8.2.12.

⚠️ Watch out: Docker’s port publishing can mask conflicts. Even if two containers expose different ports, if both ports are published to the host, only one can bind successfully. The first container to bind wins, and the second fails silently. This behavior is documented in Docker’s networking documentation, which explains that when multiple containers publish the same host port, the first one to start successfully binds the port while subsequent containers fail to start or bind silently.

Why Docker Isolates Container Networks by Default

Docker creates an internal bridge network for each compose stack. Services inside one stack can’t see ports exposed by another stack unless you explicitly publish them to the host. In this case, SGLang published port 30000, but the WordPress stack also published port 8000. Both ports were open on the host, but only one could be bound to the host’s IP at a time. The first container to bind port 8000 won, and SGLang’s traffic never reached OpenWebUI.

⚠️ Watch out: Docker’s default bridge network (bridge) does not allow cross-stack communication. If you need services in different stacks to communicate, you must either:

• Publish ports explicitly (as in this case), or
• Use a custom network with external: true in your compose files.

According to Red Hat’s learning community, port conflicts in Docker often stem from this isolation model, where services in separate networks cannot communicate unless ports are explicitly published. This isolation is intentional for security and resource management but requires careful configuration when services need to interact.

The Fix That Took Ten Seconds

Edit /data/config/docker-compose.yml and change the OpenWebUI environment variable to point to port 30000:

environment:
  OPENAI_API_BASE_URL: https://forums.docker.com/t/docker-kills-all-processes-after-5-min-and-then-restarts-again-automatically/142764/v1

Then restart OpenWebUI:

cd /data/config && docker compose up -d open-webui

⚠️ Watch out: If you’re using Docker Compose v2, the command is docker compose (no hyphen). For v1, use docker-compose. Mixing them up can lead to errors like No such service: open-webui. This distinction is critical because Docker Compose v2 integrates directly with the Docker CLI, while v1 requires a separate binary. The error occurs because the v1 command does not recognize the v2 syntax.

OpenWebUI immediately listed all SGLang models. No rebuilds, no extra config, just a single line change and a compose restart.

⚠️ Watch out: If OpenWebUI still doesn’t list models after the restart, check the logs:

docker compose logs open-webui

Look for errors like Connection refused or Timeout when calling the SGLang API. These errors typically indicate that the API endpoint is unreachable, which could be due to incorrect port configuration, network isolation, or firewall rules blocking the connection.

What to Watch Out for Next Time

• Always run netstat -tulnp or its modern replacement ss -tulnp before assuming a port is free. This reveals which processes are bound to which ports, including Docker containers. The ss command is preferred in modern Linux distributions as it is faster and more reliable than netstat, which is deprecated in many distributions.
• Use docker compose ps to list every running stack and its published ports. This helps identify conflicts before they cause issues. For example, if two stacks publish the same host port, only one will bind successfully, leading to silent failures in the other service.
• If you migrate stacks (like I did from WordPress to Astro), clean up the old compose files and prune stopped containers:

docker compose -f /data/old-wordpress/docker-compose.yml down
docker system prune --volumes

⚠️ Watch out: docker system prune --volumes removes all unused volumes, not just those from the old stack. This can delete important data if you’re not careful. Always back up volumes before pruning. For instance, if you’re using Docker volumes for databases or application data, pruning without a backup can result in data loss. Consider using docker volume ls to identify critical volumes before running the prune command.

• Check for port conflicts before deploying new services. Use ss -tulnp to verify port availability. This proactive approach prevents issues like the one described in this article, where a port conflict went unnoticed until a service failed to start.
• If you’re using Docker Desktop, check the Resources > Network tab for port mappings. This can help identify conflicts visually. Docker Desktop provides a graphical interface to monitor port usage, making it easier to spot conflicts without using command-line tools.
• Avoid hardcoding IP addresses like 172.17.0.1 in your configs. Use Docker’s internal DNS instead (e.g., sglang:30000 if both services are in the same network).

⚠️ Watch out: Hardcoded IPs can break if Docker’s network configuration changes. For example, if you restart Docker or change the bridge network settings, the IP might change, breaking your connections. Docker’s internal DNS resolves service names to their respective IP addresses dynamically, making it a more reliable solution for service-to-service communication.

• If you’re using Kubernetes, port conflicts are handled differently. You’ll need to check kubectl get svc and kubectl describe svc <service-name> to identify conflicts.

⚠️ Watch out: In Kubernetes, port conflicts can cause pods to crash or fail to start. Always check the events:

kubectl get events --sort-by='.metadata.creationTimestamp'

Port conflicts in Kubernetes often manifest as pod failures or crashes, and the events log provides critical information about why a pod failed to start. For example, if two services try to bind to the same port, Kubernetes will prevent both from starting, and the events log will indicate the conflict.

• If you’re using Podman instead of Docker, port conflicts are handled similarly, but the commands differ. Use podman ps and podman port to check port mappings.

⚠️ Watch out: Podman’s default network mode is different from Docker’s. If you’re migrating from Docker to Podman, review Podman’s network documentation to avoid surprises. Podman uses a different networking model, which can lead to unexpected port conflicts if not configured properly. For example, Podman’s rootless mode uses a different network namespace, which may require additional configuration to allow port publishing.

⚠️ Watch out: If you’re using a reverse proxy like Nginx or Traefik, port conflicts can occur if multiple services try to bind to the same port (e.g., 80 or 443). Always check your proxy’s configuration for duplicate bindings. Reverse proxies consolidate multiple services under a single port, so conflicts can arise if multiple services attempt to bind to the same port. For example, if two services try to bind to port 80, only one will succeed, and the other will fail silently.

What I Actually Use

• Mistral Small 4: runs locally on SGLang v0.1.12 with 8 GB VRAM.
• OpenWebUI: connects to SGLang via the corrected API base URL (version 1.5.1).
• Astro Webshop: replaced the old WordPress stack (version 5.9.3) and freed port 8000.