docs: Add readme.md

2026-06-03 23:47:19 +00:00 · 2026-06-03 23:47:19 +00:00 · 5ca6377462
commit 5ca6377462
parent 10b772807d
1 changed files with 97 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,97 @@
+# Voyager Homelab — Docker Stack
+
+Self-hosted infrastructure running on an HP t630 thin client (Ubuntu Server).
+All services are exposed externally via [Pangolin](https://github.com/fosrl/pangolin) reverse proxy tunnel through PMS1 (`tunnel.pelagiamarine.com`).
+
+---
+
+## Architecture
+
+```
+Client
+  └── Pangolin (PMS1 VPS) ── Newt tunnel ──► Voyager (192.168.1.55)
+                                                ├── Pi-hole :53
+                                                ├── Unbound :5335
+                                                ├── dnscrypt-proxy :5053
+                                                ├── Vaultwarden :8000
+                                                ├── Forgejo :3000
+                                                ├── Karakeep :3000
+                                                └── Resilio Sync :8888
+```
+
+### DNS Chain
+```
+LAN Devices → Pi-hole (ad blocking) → Unbound (recursive) → dnscrypt-proxy (DoH) → Cloudflare/Quad9
+```
+
+---
+
+## Services
+
+### DNS (`dns/`)
+| Service | Role | Port |
+|---|---|---|
+| Pi-hole | Network-wide ad blocking | 53 (public) |
+| Unbound | Recursive DNS resolver + DNSSEC | 5335 (internal) |
+| dnscrypt-proxy | DNS-over-HTTPS encryption | 5053 (internal) |
+
+Pi-hole is the only DNS service exposed to the LAN. Unbound and dnscrypt-proxy are internal to the Docker network.
+
+### Vaultwarden (`vaultwarden/`)
+Self-hosted password manager, compatible with all Bitwarden clients.
+- **URL:** `https://vaultwarden.tunnel.pelagiamarine.com`
+- **Image:** `vaultwarden/server:latest`
+
+### Forgejo (`forgejo/`)
+Self-hosted Git mirror. Primary instance lives on PMS1 (`git.pelagiamarine.com`).
+This instance is a push mirror — automatically receives commits from PMS1.
+- **URL:** `https://git.tunnel.pelagiamarine.com`
+- **Image:** `codeberg.org/forgejo/forgejo:10`
+- **SSH:** port `22222`
+
+### Karakeep (`karakeep/`)
+Self-hosted bookmark manager with AI tagging, full-page archiving, and screenshots.
+- **URL:** `https://bookmarks.tunnel.pelagiamarine.com`
+
+### Resilio Sync (`resilio/`)
+P2P sync for receiving PostgreSQL database backups from PMS1.
+Paired with PMS1's Resilio instance which runs a nightly `pg_dump` cron.
+- **URL:** `https://sync.tunnel.pelagiamarine.com`
+- **Sync folder:** `~/backups/postgres/`
+
+### Newt (`newt/`)
+Pangolin tunnel client. Creates an outbound tunnel to PMS1 (87.76.191.133),
+allowing Pangolin/Traefik to route `*.tunnel.pelagiamarine.com` traffic
+back to Voyager without any open inbound ports.
+
+---
+
+## Host Network
+
+| Detail | Value |
+|---|---|
+| Hostname | voyager |
+| LAN IP | `192.168.1.55` (static) |
+| IPv6 | `2405:201:24:38a4::55/64` (static) |
+| OS | Ubuntu Server 24.04 |
+| Hardware | HP t630 thin client |
+
+---
+
+## Related Infrastructure
+
+| Service | Host | URL |
+|---|---|---|
+| Pangolin (reverse proxy) | PMS1 VPS | `pangolin.pelagiamarine.com` |
+| Forgejo (primary) | PMS1 VPS | `git.pelagiamarine.com` |
+| Resilio (primary) | PMS1 VPS | `resilio.pelagiamarine.com` |
+| Pelagia Portal (Next.js) | PMS1 VPS | `pms.pelagiamarine.com` |
+
+---
+
+## Setup Notes
+
+- Port 53 requires disabling `systemd-resolved` stub listener before starting the DNS stack
+- Unbound is built from a custom Dockerfile (Alpine-based) due to scratch image limitations in `klutchell/unbound`
+- dnscrypt-proxy cache directory requires `chown 1000:1000` for write permissions
+- Forgejo `ROOT_URL` must be set to the Pangolin tunnel URL to avoid redirect loops when accessed locally