Add README.me

2026-03-16 19:19:07 +00:00
commit 0e93efa3d9
1 changed files with 105 additions and 0 deletions
--- a/README.me
+++ b/README.me
@@ -0,0 +1,105 @@
+# Self-Hosted Git Service – Public Architecture
+
+## Overview
+
+A self-hosted Gitea instance running on a home server, made publicly accessible via a cheap VPS (1 vCPU, 1 GB RAM, 10 GB SSD) acting as a secure entry point.
+
+## Architecture
+
+```
+                        Internet
+                           │
+                           ▼
+                ┌─────────────────────┐
+                │   VPS (Debian)      │
+                │   Public IPv4       │
+                │                     │
+                │   WireGuard Tunnel  │
+                │   iptables NAT      │
+                │   (Port 80/443 →)   │
+                └─────────┬───────────┘
+                          │
+                    WireGuard Tunnel
+                    (encrypted, UDP)
+                          │
+                          ▼
+          ┌───────────────────────────────┐
+          │  Home Network                 │
+          │                               │
+          │  ┌─────────────────────────┐  │
+          │  │ LXC: Reverse Proxy      │  │
+          │  │                         │  │
+          │  │ Caddy                   │  │
+          │  │ - Auto TLS (Let's Enc.) │  │
+          │  │ - Reverse Proxy → Gitea │  │
+          │  └────────────┬────────────┘  │
+          │               │               │
+          │          LAN Bridge           │
+          │               │               │
+          │  ┌────────────▼────────────┐  │
+          │  │ LXC: Gitea              │  │
+          │  │                         │  │
+          │  │ Git Hosting (HTTPS)     │  │
+          │  │ Web UI + API            │  │
+          │  └─────────────────────────┘  │
+          │                               │
+          │        Proxmox VE Host        │
+          └───────────────────────────────┘
+```
+
+## Traffic Flow
+
+1. User visits `https://git.example.com`
+2. DNS resolves to VPS public IP
+3. VPS forwards port 80/443 through WireGuard tunnel via iptables NAT
+4. Caddy (in LXC) terminates TLS with auto-provisioned Let's Encrypt certificate
+5. Caddy reverse-proxies request to Gitea (LXC) over LAN
+6. Gitea serves the response back through the same path
+
+## Components
+
+| Component | Role | Environment |
+|-----------|------|-------------|
+| VPS (1€/month) | Public entry point, WireGuard endpoint, port forwarding | Debian, cloud-hosted |
+| WireGuard | Encrypted site-to-site tunnel between VPS and home network | Both sides |
+| Caddy | Reverse proxy with automatic HTTPS (Let's Encrypt) | LXC on Proxmox |
+| Gitea | Self-hosted Git service (web UI, API, HTTPS clone) | LXC on Proxmox |
+| Proxmox VE | Hypervisor managing all local containers | Bare-metal, home server |
+
+## Design Decisions
+
+**WireGuard over Tailscale/Headscale**
+Only two endpoints with a fixed public IP on the VPS side – a simple point-to-point WireGuard tunnel is sufficient. No need for mesh networking, NAT traversal, or a coordination server. Tailscale/Headscale can be added later if the setup grows.
+
+**Caddy over NGINX**
+Caddy provides automatic TLS certificate provisioning and renewal with zero configuration. The entire reverse proxy config is 6 lines.
+
+**Reverse Proxy in separate LXC**
+Keeps the proxy isolated from both the hypervisor and the application. Adding new services only requires editing the Caddyfile – no changes to the VPS or tunnel needed.
+
+**TLS termination at home, not on VPS**
+The VPS only forwards encrypted traffic. TLS is terminated by Caddy in the home network, keeping certificate management local and the VPS stateless.
+
+## Extensibility
+
+Adding a new public service requires three steps:
+
+1. Deploy the service on Proxmox (VM or LXC)
+2. Add a DNS A-record pointing to the VPS
+3. Add a `reverse_proxy` block to the Caddyfile:
+   ```
+   newservice.example.com {
+       reverse_proxy <local-ip>:<port>
+   }
+   ```
+
+No changes to the VPS, tunnel, or firewall needed.
+
+## Security
+
+- VPS has no application logic – it only forwards traffic
+- WireGuard provides authenticated, encrypted communication between sites
+- TLS certificates are automatically managed by Caddy (Let's Encrypt)
+- Gitea is not directly exposed to the internet
+- SSH hardened: key-only authentication, no root login
+- VPS firewall managed at provider level (only SSH, HTTP, HTTPS, WireGuard open)