EZ-Homelab/docs/ports-in-use.md

Ports in Use

This document tracks all ports used by services in the AI-Homelab. Update this document whenever services are added or ports are changed.

Core Stack (core.yml)

Service	Port	Protocol	Purpose	Internal Port
Traefik	80	TCP	HTTP (redirects to HTTPS)	80
Traefik	443	TCP	HTTPS	443
Traefik	8080	TCP	Dashboard (protected)	8080

Infrastructure Stack (infrastructure.yml)

Service	Port	Protocol	Purpose	Internal Port
Dockge	5001	TCP	Web UI	5001
Pi-hole	53	TCP/UDP	DNS	53
Docker Proxy	127.0.0.1:2375	TCP	Docker API proxy	2375

Home Assistant Stack (homeassistant.yml)

Service	Port	Protocol	Purpose	Internal Port
MotionEye	8765	TCP	Web UI	8765
Mosquitto	1883	TCP	MQTT	1883
Mosquitto	9001	TCP	MQTT Websockets	9001

Monitoring Stack (monitoring.yml)

Service	Port	Protocol	Purpose	Internal Port
Prometheus	9090	TCP	Web UI/Metrics	9090

VPN Stack (vpn.yml)

Service	Port	Protocol	Purpose	Internal Port
Gluetun	8888	TCP	HTTP proxy	8888
Gluetun	8388	TCP/UDP	Shadowsocks	8388
Gluetun	8081	TCP	qBittorrent Web UI	8080
Gluetun	6881	TCP/UDP	qBittorrent	6881

Port Range Reference

Range	Usage
1-1023	System ports (well-known)
1024-49151	Registered ports
49152-65535	Dynamic/private ports

Common Port Conflicts

• Port 80/443: Used by Traefik for HTTP/HTTPS
• Port 53: Used by Pi-hole for DNS
• Port 2375: Used by Docker Proxy (localhost only)
• Port 5001: Used by Dockge
• Port 5432: Used by PostgreSQL
• Port 6379: Used by Redis
• Port 8080: Used by Traefik dashboard
• Port 9090: Used by Prometheus

Adding New Services

When adding new services:

1. Check this document for available ports
2. Choose ports that don't conflict with existing services
3. Update this document with new port mappings
4. Consider using Traefik labels instead of direct port exposure for web services

Port Planning Guidelines

• Web services: Use Traefik labels (no direct ports needed)
• Databases: Use internal networking only (no external ports)
• VPN services: Route through Gluetun for security
• Development tools: Consider localhost-only binding (127.0.0.1:port)
• Monitoring: Use high-numbered ports (9000+ range)

Updating This Document

This document should be updated whenever:

• New services are added to any stack
• Existing services change their port mappings
• Services are removed from stacks
• Network configurations change

Run this command to find all port mappings in compose files:

grep -r "ports:" docker-compose/ | grep -v "^#" | sort