copilot Instructions improvements

and documentation updates
2026-01-21 18:52:40 -05:00
parent c6d14d4904
commit 30e0481685
10 changed files with 315 additions and 167 deletions
--- a/docs/ports-in-use.md
+++ b/docs/ports-in-use.md
@@ -0,0 +1,98 @@
+# 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](../docker-compose/core.yml))
+
+| Service | Port | Protocol | Purpose | Internal Port |
+|---------|------|----------|---------|---------------|
+| [Traefik](../service-docs/traefik.md) | 80 | TCP | HTTP (redirects to HTTPS) | 80 |
+| [Traefik](../service-docs/traefik.md) | 443 | TCP | HTTPS | 443 |
+| [Traefik](../service-docs/traefik.md) | 8080 | TCP | Dashboard (protected) | 8080 |
+
+## Infrastructure Stack ([infrastructure.yml](../docker-compose/infrastructure.yml))
+
+| Service | Port | Protocol | Purpose | Internal Port |
+|---------|------|----------|---------|---------------|
+| [Dockge](../service-docs/dockge.md) | 5001 | TCP | Web UI | 5001 |
+| [Pi-hole](../service-docs/pihole.md) | 53 | TCP/UDP | DNS | 53 |
+| [Docker Proxy](../service-docs/docker-proxy.md) | 127.0.0.1:2375 | TCP | Docker API proxy | 2375 |
+
+## Development Stack ([development.yml](../docker-compose/development.yml))
+
+| Service | Port | Protocol | Purpose | Internal Port |
+|---------|------|----------|---------|---------------|
+| [PostgreSQL](../service-docs/postgresql.md) | 5432 | TCP | Database | 5432 |
+| [Redis](../service-docs/redis.md) | 6379 | TCP | Cache/Database | 6379 |
+
+## Home Assistant Stack ([homeassistant.yml](../docker-compose/homeassistant.yml))
+
+| Service | Port | Protocol | Purpose | Internal Port |
+|---------|------|----------|---------|---------------|
+| [MotionEye](../service-docs/motioneye.md) | 8765 | TCP | Web UI | 8765 |
+| [Mosquitto](../service-docs/mosquitto.md) | 1883 | TCP | MQTT | 1883 |
+| [Mosquitto](../service-docs/mosquitto.md) | 9001 | TCP | MQTT Websockets | 9001 |
+
+## Monitoring Stack ([monitoring.yml](../docker-compose/monitoring.yml))
+
+| Service | Port | Protocol | Purpose | Internal Port |
+|---------|------|----------|---------|---------------|
+| [Prometheus](../service-docs/prometheus.md) | 9090 | TCP | Web UI/Metrics | 9090 |
+
+## VPN Stack ([vpn.yml](../docker-compose/vpn.yml))
+
+| Service | Port | Protocol | Purpose | Internal Port |
+|---------|------|----------|---------|---------------|
+| [Gluetun](../service-docs/gluetun.md) | 8888 | TCP | HTTP proxy | 8888 |
+| [Gluetun](../service-docs/gluetun.md) | 8388 | TCP/UDP | Shadowsocks | 8388 |
+| [Gluetun](../service-docs/gluetun.md) | 8081 | TCP | qBittorrent Web UI | 8080 |
+| [Gluetun](../service-docs/gluetun.md) | 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:
+```bash
+grep -r "ports:" docker-compose/ | grep -v "^#" | sort
+```
--- a/docs/proxying-external-hosts.md
+++ b/docs/proxying-external-hosts.md
@@ -14,7 +14,7 @@ Traefik can proxy services that aren't running in Docker, such as:

 ### Step 1: Create External Service Configuration

-Create a file in `/opt/stacks/traefik/dynamic/external-hosts.yml`:
+Create a file in `/opt/stacks/traefik/dynamic/` with the format 'external-host-servername.yml'

 ```yaml
 http:
@@ -71,7 +71,11 @@ Visit `https://ha.yourdomain.duckdns.org` - Traefik will:

 ## Method 2: Using Docker Labels (Dummy Container)

-If you prefer managing routes via Docker labels (so the AI can modify them), create a dummy container:
+If you prefer managing routes via Docker labels, create a dummy container:
+
+>This can be resource intensive with serveral services running.  
+Not recomended due to unnecessary resource/power consumption.  
+Don't try it on a Raspberry Pi

 ### Create a Label Container

@@ -108,13 +112,6 @@ cd /opt/stacks/external-proxies
 docker compose up -d
 ```

-## Method 3: Hybrid Approach (File + Docker Discovery)
-
-Combine both methods for maximum flexibility:
- Use file provider for static external hosts
- Use Docker labels for frequently changing services
- AI can manage both!
-
 ## Common External Services to Proxy

 ### Home Assistant (Raspberry Pi)
@@ -134,34 +131,6 @@ router-admin:
    - authelia@docker  # Add SSO protection
 ```

-### Proxmox Server
-```yaml
-proxmox:
-  rule: "Host(`proxmox.yourdomain.duckdns.org`)"
-  service: https://192.168.1.100:8006
-  middlewares:
-    - authelia@docker
-  # Note: Use https:// if backend uses HTTPS
-```
-
-### TrueNAS/FreeNAS
-```yaml
-truenas:
-  rule: "Host(`nas.yourdomain.duckdns.org`)"
-  service: http://192.168.1.200:80
-  middlewares:
-    - authelia@docker
-```
-
-### Security Camera NVR
-```yaml
-nvr:
-  rule: "Host(`cameras.yourdomain.duckdns.org`)"
-  service: http://192.168.1.10:80
-  middlewares:
-    - authelia@docker  # Definitely protect cameras!
-```
-
 ## Advanced Configuration

 ### WebSocket Support
--- a/docs/resource-limits-template.md
+++ b/docs/resource-limits-template.md
@@ -139,7 +139,7 @@ calibre_web:      # Ebook manager
  template: web_service
  notes: "Light web app with database"

-# Downloaders Stack
+# VPN Stack
 qbittorrent:      # Torrent client
  template: downloader_service
  notes: "Network I/O heavy, moderate CPU for hashing"
--- a/docs/services-overview.md
+++ b/docs/services-overview.md
@@ -6,11 +6,13 @@ This document provides a comprehensive overview of all 50+ pre-configured servic

 | Stacks (10) | Services (70 + 6db) | SSO | Storage | Access URLs |
 |-------|----------|-----|---------|-------------|
-| **📦 core.yaml (4)** | **Deploy First** | | | |
+| **📦 core.yaml (3)** | **Deploy First** | | | |
 | ├─ DuckDNS | Dynamic DNS updater | - | /opt/stacks/core/duckdns | No UI |
 | ├─ Traefik | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} |
-| ├─ Authelia | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
-| └─ Gluetun | VPN (Surfshark) | - | /opt/stacks/core/gluetun | No UI |
+| └─ Authelia | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
+| **🔒 vpn.yaml (2)** | **VPN Services** | | | |
+| ├─ Gluetun | VPN (Surfshark) | - | /opt/stacks/vpn/gluetun | No UI |
+| └─ qBittorrent | Torrent (via VPN) | ✓ | /mnt/downloads | qbit.${DOMAIN} |
 | **🔧 infrastructure.yaml** (12) | | | | |
 | ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
 | ├─ Portainer | Container management | ✓ | /opt/stacks/infrastructure | portainer.${DOMAIN} |
@@ -31,8 +33,7 @@ This document provides a comprehensive overview of all 50+ pre-configured servic
 | ├─ Jellyfin | Media server (OSS) | ✗ | /mnt/media, /mnt/transcode | jellyfin.${DOMAIN} |
 | ├─ Sonarr | TV automation | ✓ | /opt/stacks/media, /mnt/media | sonarr.${DOMAIN} |
 | ├─ Radarr | Movie automation | ✓ | /opt/stacks/media, /mnt/media | radarr.${DOMAIN} |
-| ├─ Prowlarr | Indexer manager | ✓ | /opt/stacks/media | prowlarr.${DOMAIN} |
-| └─ qBittorrent | Torrent (via VPN) | ✓ | /mnt/downloads | qbit.${DOMAIN} |
+| └─ Prowlarr | Indexer manager | ✓ | /opt/stacks/media | prowlarr.${DOMAIN} |
 | **📚 media-extended.yaml** (10) | | | | |
 | ├─ Readarr | Ebooks/Audiobooks | ✓ | /opt/stacks/media-ext, /mnt/media | readarr.${DOMAIN} |
 | ├─ Lidarr | Music manager | ✓ | /opt/stacks/media-ext, /mnt/media | lidarr.${DOMAIN} |