303 lines
5.3 KiB
Markdown
303 lines
5.3 KiB
Markdown
# Palladino Homelab / Local Network Architecture
|
||
|
||
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 |