SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdocker-networking

docker-networking

Deployment & operations

View repository

Updated 10-15 21:48

About this skill

Docker Networking — Network Configuration and Container Communication

Comprehensive guidance for Docker networking modes, configuration, and troubleshooting.

When to Use

ALWAYS use this skill when the user mentions:

  • "docker network", "container networking"
  • "bridge network", "host network", "overlay network"
  • "port mapping", "publish port"
  • "how do containers communicate", "cross-container communication"
  • "network not working", "network troubleshooting"

Network Mode Comparison

Mode Isolation Use Case Cross-Host?
bridge (default) Container-level Single-host containers ❌
host None (share host) Max performance, no isolation ❌
overlay Container-level Swarm multi-host ✅
none Full No networking needed ❌
macvlan/ipvlan MAC/IP-level Legacy apps needing physical IP ✅

Custom Bridge Network (Recommended)

# Create a custom network
docker network create --driver bridge mynet

# Run containers on it
docker run -d --name app1 --network mynet nginx:alpine
docker run -d --name app2 --network mynet nginx:alpine

# DNS resolution works automatically
docker exec app1 ping app2    # ✅ responds
docker exec app1 nslookup app2  # ✅ resolves

# Benefits over default bridge:
# - Automatic DNS resolution
# - Container isolation from default bridge
# - Can connect/disconnect at runtime

Port Publishing

# Basic port mapping
docker run -p 8080:80 nginx     # host:8080 → container:80
docker run -p 8080              # random host port → container:8080
docker run -P nginx             # publish all EXPOSE'd ports to random host ports

# Multiple ports
docker run -p 8080:80 -p 8443:443 nginx

# Bind to specific interface
docker run -p 127.0.0.1:8080:80 nginx  # only localhost

Service Discovery

Custom bridge network provides automatic DNS:

┌──────────────────────────────────┐
│  my-network (bridge)             │
│                                  │
│  ┌──────┐  ┌──────┐  ┌──────┐   │
│  │ app1 │  │ app2 │  │  db  │   │
│  └──┬───┘  └──┬───┘  └──┬───┘   │
│     │         │         │        │
│     └─── DNS: app2 → 172.18.0.3 │
│          DNS: db → 172.18.0.4   │
└──────────────────────────────────┘

app1 can connect to db:5432 directly — no IP needed!

Overlay Network (Swarm)

# Create overlay for multi-host
docker network create --driver overlay --attachable my-overlay

# In compose:
networks:
  backend:
    driver: overlay

Network Troubleshooting

# Inspect network details
docker network inspect mynet

# Test connectivity from container
docker exec app1 ping -c 3 app2
docker exec app1 nslookup db
docker exec app1 curl http://app2:8080/health

# Check iptables (host)
sudo iptables -t nat -L DOCKER -n

Workflow — Recommended Configuration Process

Step 1: Determine requirements: inter-container communication? port exposure? cross-host? Choose the network mode Step 2: Create a network: docker network create --driver bridge mynet Step 3: Start containers: docker run -d --network mynet --name db mysql + docker run -d --network mynet --name api myapp Step 4: Verify connectivity: docker exec api ping db(service name DNS resolution) Step 5: Troubleshoot issues: docker network inspect mynet → docker exec api nslookup db

Gotchas — Common Pitfalls

  • Default bridge no DNS: Containers on the default bridge CANNOT resolve each other by name. → Recovery: docker network create mynet && docker run --network mynet ...; always use custom bridge networks.
  • Port already in use: -p 8080:80 fails if host port 8080 is taken. → Recovery: lsof -i :8080 to find the process; use -p 8081:80 or -p 80 for random host port.
  • Mac host networking limitation: --network host on Docker Desktop (Mac) joins the VM's network, not the Mac's. → Recovery: Publish ports with -p instead of --network host.
  • Overlay without Swarm: Overlay networks only work with Swarm mode. → Recovery: docker swarm init first, or add --attachable flag for standalone containers.
  • EXPOSE does NOT publish: EXPOSE in Dockerfile is documentation only. → Recovery: Always use -p or Compose ports: to actually make ports accessible.

Boundary — Capability Boundaries (Applicable and Non-Applicable Scenarios)

Category Scenario Description
✅ Can do Single-host container network configuration bridge/host/none mode selection
✅ Can do Inter-container DNS communication Custom bridge network + service name resolution
✅ Can do Port publishing -p host:container port mapping
⚠️ Conditional Cross-host communication Requires overlay network + Swarm mode
⚠️ Conditional macOS --network host Behavior differs from Linux; recommend using -p instead
❌ Out of scope K8s network policies (NetworkPolicy) Use docker-production + K8s documentation
❌ Out of scope External load balancing (Nginx/HAProxy) Infrastructure layer
❌ Out of scope Fine-grained iptables/nftables configuration Linux network management

When NOT to Use This Skill

❌ Skip ✅ Use Instead
Docker basics docker-basics
Running containers docker-run
Compose networking docker-compose (compose handles network creation automatically)
Kubernetes networking K8s documentation

Security & Stability

  • Use --internal flag for networks that should not have internet access.
  • Encrypt overlay network traffic: --opt encrypted=true.
  • Avoid --network host in production — no network isolation.
  • No executable scripts bundled. Guidance only.

📚 Official Documentation References

Documentation Address
Docker networking overview https://docs.docker.com/network/
docker network commands https://docs.docker.com/reference/cli/docker/network/
Network drivers https://docs.docker.com/network/drivers/
Bridge network https://docs.docker.com/network/bridge/
Overlay network https://docs.docker.com/network/overlay/
Port publishing https://docs.docker.com/network/#published-ports

🧭 Docker Skills Journey

📍 You are here: docker-networking — Network configuration

← Previous: docker-run | → Next: docker-compose

FAQ

Q1: How can I quickly get started with this skill? A: Refer to the Quick Start section above and follow the steps.

Q2: What should I do if I encounter a version incompatibility issue? A: Check dependency versions, use a lock file to pin them, and refer to the Common Pitfalls section.

Q3: How can I use it in a production environment? A: Refer to the Best Practices section, ensure the configuration is correct, and set up monitoring and logging properly.

Q4: How can performance be optimized? A: Refer to the performance optimization documentation and use techniques such as caching and indexing.

Q5: How can I contribute or report issues? A: Submit an Issue or Pull Request in the GitHub repository.

Q6: Is Chinese supported? A: Chinese documentation and Chinese comments are supported; see the Localization section for details.