tomevault-io Docker Networking Knowledge Base
Network configuration patterns and communication strategies for PHP Docker stacks.
Network Types
| Type | Driver | Use Case | Isolation | Performance |
|---|---|---|---|---|
| Bridge | bridge |
Default single-host | Container-level | Good |
| Host | host |
Maximum performance | None (shares host) | Best |
| Overlay | overlay |
Multi-host (Swarm/K8s) | Container-level | Moderate |
| None | none |
Complete isolation | Full | N/A |
| Macvlan | macvlan |
Direct LAN access | Network-level | Good |
PHP-FPM + Nginx Communication
TCP Socket (Default in Docker)
┌─────────────────────────────────────────────────────────────────────────────┐
│ TCP SOCKET COMMUNICATION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client ──▶ :80 ──▶ ┌─────────┐ TCP :9000 ┌──────────┐ │
│ │ Nginx │ ──────────▶ │ PHP-FPM │ │
│ └─────────┘ └──────────┘ │
│ │
│ Nginx config: fastcgi_pass php:9000; │
│ PHP-FPM config: listen = 0.0.0.0:9000 │
│ │
│ Pros: Works across containers, simple setup, scalable │
│ Cons: Slight overhead vs Unix socket │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Unix Socket (Shared Volume)
┌─────────────────────────────────────────────────────────────────────────────┐
│ UNIX SOCKET COMMUNICATION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client ──▶ :80 ──▶ ┌─────────┐ /sock/fpm ┌──────────┐ │
│ │ Nginx │ ──────────▶ │ PHP-FPM │ │
│ └────┬────┘ └────┬─────┘ │
│ │ shared volume │ │
│ └────────┐ ┌────────────┘ │
│ ▼ ▼ │
│ ┌──────────────┐ │
│ │ /var/run/php/ │ │
│ │ php-fpm.sock │ │
│ └──────────────┘ │
│ │
│ Nginx config: fastcgi_pass unix:/var/run/php/php-fpm.sock; │
│ PHP-FPM config: listen = /var/run/php/php-fpm.sock │
│ │
│ Pros: ~5-10% faster, no TCP overhead │
│ Cons: Requires shared volume, harder to scale │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Compose configuration for Unix socket:
services:
php:
volumes:
- php-socket:/var/run/php
nginx:
volumes:
- php-socket:/var/run/php:ro
volumes:
php-socket:
DNS Resolution in Compose
Docker Compose provides automatic DNS resolution using service names.
┌──────────────────────────────────────────────────────────┐
│ DNS RESOLUTION │
├──────────────────────────────────────────────────────────┤
│ │
│ Service Name ──▶ Container IP │
│ ──────────────────────────────────── │
│ postgres ──▶ 172.20.0.2 │
│ redis ──▶ 172.20.0.3 │
│ rabbitmq ──▶ 172.20.0.4 │
│ php ──▶ 172.20.0.5 │
│ nginx ──▶ 172.20.0.6 │
│ │
│ Resolution scope: within same network only │
│ Resolver: Docker embedded DNS (127.0.0.11) │
│ │
└──────────────────────────────────────────────────────────┘
PHP connection strings using service names:
// PostgreSQL
'postgresql://app:secret@postgres:5432/app'
// Redis
'redis://redis:6379'
// RabbitMQ
'amqp://guest:guest@rabbitmq:5672/%2f'
// Elasticsearch
'http://elasticsearch:9200'
DNS Aliases
services:
postgres:
networks:
backend:
aliases:
- db
- database
- pg
Port Mapping Strategies
| Pattern | Syntax | Visibility | Use Case |
|---|---|---|---|
| Published | ports: ["8080:80"] |
Host + containers | Dev access, public services |
| Exposed | expose: ["9000"] |
Containers only | Internal services (FPM) |
| Host binding | ports: ["127.0.0.1:5432:5432"] |
Localhost only | Databases in dev |
| Random host | ports: ["5432"] |
Random host port | CI, parallel testing |
Recommended Port Mapping
services:
# Public-facing — bind to all interfaces
nginx:
ports:
- "80:80"
- "443:443"
# Internal service — expose only (no host port)
php:
expose:
- "9000"
# Database — localhost only (dev security)
postgres:
ports:
- "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
# Management UI — localhost only
rabbitmq:
ports:
- "127.0.0.1:${RABBITMQ_MGMT_PORT:-15672}:15672"
Network Segmentation
networks:
frontend:
driver: bridge
# Public-facing services (Nginx, Mailhog UI)
backend:
driver: bridge
internal: true
# Database, cache, queue — no external access
monitoring:
driver: bridge
# Prometheus, Grafana, Jaeger
Segmentation Matrix
┌─────────────────────────────────────────────────────────────────┐
│ Service │ frontend │ backend │ monitoring │ internet │
│ ────────────────┼──────────┼─────────┼────────────┼────────── │
│ Nginx │ ✓ │ │ │ ✓ │
│ PHP-FPM │ ✓ │ ✓ │ │ │
│ Worker │ │ ✓ │ │ │
│ Cron │ │ ✓ │ │ │
│ PostgreSQL │ │ ✓ │ │ │
│ Redis │ │ ✓ │ │ │
│ RabbitMQ │ │ ✓ │ │ │
│ Elasticsearch │ │ ✓ │ │ │
│ Prometheus │ │ ✓ │ ✓ │ │
│ Grafana │ │ │ ✓ │ ✓ │
│ Jaeger │ │ ✓ │ ✓ │ │
└─────────────────────────────────────────────────────────────────┘
The internal: true flag on the backend network prevents containers from reaching the internet, ensuring databases and caches are not exposed.
Inter-Container Communication
Same Network (Direct)
// Containers on the same network communicate directly via service name
$redis = new \Redis();
$redis->connect('redis', 6379);
Cross-Network (Shared Service)
services:
php:
networks:
- frontend
- backend # PHP needs both to talk to Nginx AND database
postgres:
networks:
- backend # Only backend — no direct external access
Service Discovery Pattern
// Use environment variables for service endpoints
$dbHost = getenv('DATABASE_HOST') ?: 'postgres';
$redisHost = getenv('REDIS_HOST') ?: 'redis';
$amqpHost = getenv('AMQP_HOST') ?: 'rabbitmq';
host.docker.internal for Local Development
Access host machine services from within containers:
services:
php:
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
# Connect to services running on host machine
XDEBUG_CONFIG: "client_host=host.docker.internal"
| Platform | host.docker.internal | Notes |
|---|---|---|
| Docker Desktop (Mac) | Built-in | Works automatically |
| Docker Desktop (Windows) | Built-in | Works automatically |
| Linux | Requires extra_hosts |
Use host-gateway mapping |
Troubleshooting
| Issue | Diagnosis | Solution |
|---|---|---|
| Container cannot resolve service name | Wrong network | Ensure both services share a network |
| Connection refused between containers | Port not exposed | Add expose or check service is listening |
| Intermittent DNS failures (Alpine) | musl resolver | Add options ndots:0 to resolv.conf |
| Cannot reach host machine | Missing extra_hosts | Add host.docker.internal:host-gateway |
| External access to internal service | Missing internal: true |
Mark backend network as internal |
| Port conflict on host | Port already in use | Use variable port mapping ${PORT:-5432}:5432 |
References
For service configuration examples, see docker-compose-knowledge.
For base image networking considerations, see docker-base-images-knowledge.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.