# 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