Update docs

README.md

@@ -1,3 +1,303 @@
-# Local Network Configuration
+# Palladino Homelab / Local Network Architecture
 
-This repo describes my local network configuration and contains resources for reconstructing it or at least remembering what has been done. 
+This repository documents the structure and configuration of the Palladino home network and homelab environment. The goal is to provide a clear reference for how services are deployed, exposed, and maintained so that the system can be debugged, rebuilt, or migrated in the future.
+
+---
+
+# Overview
+
+The Palladino home network hosts several self‑hosted services running primarily on a Synology NAS using Docker containers. The system uses UniFi networking equipment for routing, NAT, and firewalling.
+
+External access to services is provided through a combination of:
+
+• Public DNS
+• UniFi port forwarding
+• Synology DSM reverse proxy
+• Docker containers
+
+TLS certificates are managed automatically by Synology DSM using Let’s Encrypt.
+
+---
+
+# Network Components
+
+## Router / Gateway
+
+Device: UniFi gateway (UDM Pro)
+
+Responsibilities:
+
+• Internet gateway
+• NAT and firewall
+• Port forwarding
+• DHCP
+• Local network routing
+
+Relevant configuration area:
+
+Network → Firewall & Security → Port Forwarding
+
+---
+
+# DNS
+
+Public DNS is the primary source of truth for service hostnames.
+
+Example:
+
+    gitea.palladino.io → public IP
+
+Local DNS overrides should generally be avoided for hostnames already managed by Synology’s reverse proxy. Having both DSM and a local DNS server answer for the same hostname can cause resolver conflicts.
+
+Important lesson:
+
+If DSM reverse proxy owns a hostname and a local DNS override is added for the same hostname, macOS may follow the Synology DDNS alias instead of the local IP.
+
+---
+
+# NAS / Server
+
+Device: Synology DiskStation
+Hostname: diskstation
+LAN IP: 192.168.1.67
+
+Responsibilities:
+
+• Docker container host
+• DSM reverse proxy
+• TLS certificate management
+• Storage
+
+---
+
+# Docker Services
+
+Containers are stored under:
+
+    /volume1/docker/
+
+Example structure:
+
+    /volume1/docker
+        /gitea
+        /gitea-old
+        /homeassistant
+
+Docker containers are managed via Synology Container Manager.
+
+---
+
+# Reverse Proxy
+
+Reverse proxy functionality is provided by DSM.
+
+Location:
+
+DSM → Control Panel → Login Portal → Advanced → Reverse Proxy
+
+Example rule (Gitea):
+
+Source
+
+    Protocol: HTTPS
+    Hostname: gitea.palladino.io
+    Port: 443
+
+Destination
+
+    Protocol: HTTP
+    Hostname: localhost
+    Port: 3001
+
+Request flow:
+
+    https://gitea.palladino.io
+            ↓
+    Synology reverse proxy
+            ↓
+    localhost:3001
+            ↓
+    Gitea container
+
+---
+
+# TLS Certificates
+
+Certificates are managed in:
+
+DSM → Control Panel → Security → Certificate
+
+Primary certificate:
+
+    palladino.io
+
+Subject Alternative Names include:
+
+    palladino.io
+    gitea.palladino.io
+    plex.palladino.io
+    paperless.palladino.io
+    dsm.palladino.io
+
+Important operational detail:
+
+Certificates must be explicitly assigned to services.
+
+Location:
+
+Security → Certificates → Configure
+
+Example assignment:
+
+    Service: gitea.palladino.io
+    Certificate: palladino.io
+
+---
+
+# Port Forwarding
+
+Configured in UniFi:
+
+Network → Firewall → Port Forwarding
+
+Current forwards:
+
+    443 → Synology (DSM reverse proxy)
+    80  → Synology (HTTP redirect)
+    7999 → Synology (Gitea SSH)
+
+Example rule:
+
+Name: Gitea SSH
+Protocol: TCP
+Destination Port: 7999
+Forward IP: 192.168.1.67
+Forward Port: 7999
+
+---
+
+# Gitea
+
+Gitea runs in Docker.
+
+Container ports:
+
+    22   → 7999  (SSH)
+    3000 → 3001  (Web UI)
+
+Web UI flow:
+
+    https://gitea.palladino.io
+          ↓
+    reverse proxy
+          ↓
+    localhost:3001
+          ↓
+    Gitea container
+
+Git SSH flow:
+
+    git@gitea.palladino.io:7999
+          ↓
+    UniFi port forward
+          ↓
+    NAS
+          ↓
+    Docker port mapping
+
+---
+
+# Git SSH Access
+
+Git SSH runs on port 7999.
+
+Clone example:
+
+    ssh://git@gitea.palladino.io:7999/user/repo.git
+
+Recommended SSH client configuration:
+
+    ~/.ssh/config
+
+Example:
+
+    Host gitea.palladino.io
+      HostName gitea.palladino.io
+      Port 7999
+      User git
+
+This allows shorter Git URLs:
+
+    git@gitea.palladino.io:user/repo.git
+
+---
+
+# Debugging Guide
+
+Check DNS resolution:
+
+    dig gitea.palladino.io
+
+Check system resolver (macOS):
+
+    dscacheutil -q host -a name gitea.palladino.io
+
+Test SSH connectivity:
+
+    nc -vz gitea.palladino.io 7999
+
+Expected:
+
+    Connection succeeded
+
+Trace network path:
+
+    traceroute gitea.palladino.io
+
+Expected first hop:
+
+    192.168.1.67
+
+Check ports on NAS:
+
+    netstat -tulpn | grep -E ':80|:443'
+
+---
+
+# Known Pitfalls
+
+Reverse proxy vs local DNS
+
+If a hostname used by DSM reverse proxy is overridden locally (for example via UniFi DNS), macOS may follow the Synology DDNS alias instead of the local address.
+
+Symptom:
+
+DNS lookup returns a LAN address but the system connects to the public IP.
+
+Resolution:
+
+Remove the local DNS override or avoid using the same hostname in multiple DNS authorities.
+
+---
+
+# Backup / Migration Notes
+
+If the NAS is replaced or rebuilt, the following must be recreated:
+
+- UniFi port forwarding rules
+- DSM reverse proxy rules
+- certificate assignments
+- Docker volumes under /volume1/docker
+- Gitea container configuration
+
+---
+
+# Future Improvements
+
+Possible improvements to this setup:
+
+- SSH alias configuration for cleaner Git URLs
+- centralized service inventory documentation
+- monitoring and alerts
+- docker compose definitions for all services
+- automated infrastructure documentation