This document provides ASCII diagrams showing how all of components of your NixOS configuration are wired together.
INTERNET
│
│ HTTPS (443)
│ HTTP (80)
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌──────▼──────┐
│ Caddy │ │ SSH │
│ (Port 443) │ │ (Port 22) │
│ Rate Limit │ │ │
│ TLS Term │ └─────────────┘
└───────┬────────┘
│ Reverse Proxy
┌───────────┼───────────┐
│ │ │
┌────▼────┐ ┌───▼────┐ ┌───▼─────┐
│ PDS │ │ Knot │ │ Grafana │
│ :2583 │ │ :5555 │ │ :3001 │
└────┬────┘ └───┬────┘ └────┬────┘
│ │ │
┌────▼──────────▼───────────▼────┐
│ LOCALHOST SERVICES │
│ (127.0.0.1) │
│ │
│ Spindle :6555 │
│ Spacedust :9998 │
│ Slingshot :3000 │
│ Lycan :3100 │
│ QuickDID :8080 │
│ Prometheus :9090 │
│ Node-Exporter :9100 │
└────────────┬────────────────────┘
│
│ Local Data
│
┌────────────▼────────────────────┐
│ PERSISTENT STORAGE │
│ │
│ /var/lib/pds/ │
│ /var/lib/tangled-knot/ │
│ /var/lib/postgresql/ │
│ /var/lib/grafana/ │
│ /var/lib/prometheus2/ │
└─────────────────────────────────┘
│
│ Tailscale VPN
│ (100.64.0.0/10)
│
┌───────────┴───────────┐
│ │
┌───▼────────┐ ┌──────▼──────┐
│ NixOS │ │ Homelab │
│ Server │ │ (cobh) │
│ 100.113. │ │ 100.112. │
│ 12.42 │ │ 12.44 │
│ │ │ │
│ Constella- │ │ Radicle │
│ tion :6795 │ │ Node :8776 │
│ │ │ │
│ Indigo │ │ HTTPD :8081 │
│ Relay │ │ │
│ :2470 │ │ │
└────────────┘ └─────────────┘
}}}
== Data Flow: User Request to Service ==
User Browser
│
│ 1. DNS Lookup: knot.snek.cc → VPS_IP
│
▼
┌──────────────┐
│ DNS │
│ (snek.cc) │
└──────┬───────┘
│
│ 2. HTTPS Request to VPS_IP:443
│ Host: knot.snek.cc
│
▼
┌──────────────┐ 3. Check Cert ┌──────────────┐
│ Caddy │◄─────────────────────►│ Let's Encrypt│
│ :443 │ (on-demand TLS) │ │
└──────┬───────┘ └──────────────┘
│
│ 4. Match Host Header
│ "knot.snek.cc"
│
▼
┌──────────────┐ 5. Apply Rules ┌──────────────┐
│ Rate Limit │◄─────────────────────►│ 10 req/sec │
│ Check │ │ burst 20 │
└──────┬───────┘ └──────────────┘
│
│ 6. Add Security Headers
│
▼
┌──────────────┐ 7. Forward ┌──────────────┐
│ Reverse │──────────────────────►│ Tangled │
│ Proxy │ http://127.0.0.1: │ Knot │
│ │ 5555 │ :5555 │
└──────────────┘ └──────┬───────┘
│
│ 8. Process
│ Request
▼
┌──────────────┐
│ Git Repo │
│ Operations │
└──────┬───────┘
│
│ 9. Response
│
10. Response │
◄──────────────────────────────────────┘
│
▼
User Browser
}}}
Developer Machine VPS (snek)
│ │
│ 1. Edit Secrets │
│ sops secrets/pds.yaml │
│ │
▼ │
┌──────────────┐ │
│ Plaintext │ │
│ Secrets │ │
└──────┬───────┘ │
│ │
│ 2. Encrypt with age │
│ (public key) │
│ │
▼ │
┌──────────────┐ 3. Push to Git │
│ Encrypted │─────────────────────────────►│
│ YAML File │ │
└──────────────┘ │
│
│ 4. Pull / Deploy
│ nixos-rebuild
│
▼
┌──────────────┐
│ Nix Eval │
│ (build time) │
└──────┬───────┘
│
│ 5. Generate
│ Activation
│ Scripts
▼
┌──────────────┐
│ System │
│ Activation │
│ (boot time) │
└──────┬───────┘
│
│ 6. Decrypt
│ with age
│ (SSH key)
▼
┌──────────────┐
│ Plaintext │
│ in /run/ │
│ secrets/ │
└──────┬───────┘
│
│ 7. Load into
│ Environment
▼
┌──────────────┐
│ PDS Service │
│ Process │
└──────────────┘
Key Points:
- Secrets NEVER touch of Nix store
- Decryption happens at activation (boot/deploy time)
- /run is tmpfs (RAM), survives reboot via re-decryption
- SSH host key acts as age private key
}}}
== ATProto Network Integration ==
┌─────────────────────────────────────┐
│ ATPROTO NETWORK │
│ │
┌──────────────┐ │ ┌──────────────┐ ┌────────────┐ │
│ Bluesky │ │ │ Other │ │ PLC │ │
│ AppView │ │ │ PDSs │ │ Directory │ │
│ │ │ │ │ │ │ │
│ api.bsky.app │ │ │ │ │plc.dir │ │
└──────┬───────┘ │ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │
│ │ │ │ │
│ 1. Fetch │ │ │ │
│ Posts │ │ │ │
│◄─────────┘ │ │ │
│ │ │ │
│ │ │ │
┌──────┴────────────────────┴────────────────┴──────┐ │
│ RELAY / FIREHOSE │ │
│ (WebSocket wss://bsky.network) │ │
└──────┬──────────────────────────────────────┬─────┘ │
│ │ │
│ 2. Publish Events │ │
│ │ │
▼ ▼ │
┌──────────────┐ ┌──────────────┐ │
│ Your PDS │◄─────────────────────►│ Jetstream │ │
│ pds.snek.cc │ 3. DID Resolution │ Firehose │ │
│ │──────────────────────►│ │ │
│ ┌──────────┐ │ └──────┬───────┘ │
│ │ User │ │ │ │
│ │ Repos │ │ │ │
│ │ Identity │ │ │ │
│ └──────────┘ │ │ │
└──────┬───────┘ │ │
│ │ │
│ 4. User Actions │ │
│ (Posts, Likes, etc) │ │
│ │ │
▼ │ │
┌──────────────┐ │ │
│ Firehose │──────────────────────────────┘ │
│ Publisher │ 5. Events Broadcast │
└──────────────┘ │
│ │
│ 6. Consume │
│ │
▼ │
┌──────────────────────────────────────────────────┐ │
│ YOUR INFRASTRUCTURE (snek) │ │
│ │ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ Lycan │ │ Spacedust│ │ Spindle │ │ │
│ │ Feed │ │ Indexer │ │ CI/CD │ │ │
│ │ Generator│ │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │
└──────────────────────────────────────────────────┘ │
│
└─────────────────────────────────────────────────────────┘
}}}
Legend:
───► = Depends on / Uses
──► = Optional / Can use
┌─────────────────────────────────────────────────────────────┐
│ BASE SYSTEM │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Network │ │ SSH │ │ System │ │
│ │ (DHCP) │ │ :22 │ │ Users │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ └──────────────┴──────────────┘ │
│ │ │
└───────────────────────┼──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE LAYER │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐ │
│ │ Caddy │ │ Tailscale │ │ sops-nix │ │ Nix │ │
│ │ :443 │ │ VPN │ │ Secrets │ │ Store │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └────┬────┘ │
│ │ │ │ │ │
│ └──────────────┴──────────────┴─────────────┘ │
│ │ │
└───────────────────────────┼─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SERVICE LAYER │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ DATA SERVICES │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │PostgreSQL │ │ PDS │ │ Tangled │ │ │
│ │ │ :5432 │──►│ Data │──►│ Git │ │ │
│ │ │ (Lycan) │ │ /var/lib │ │ Repos │ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ │ │
│ └────────────────────────┬────────────────────────────┘ │
│ │ │
│ ┌────────────────▼────────────────────────────┐ │
│ │ APPLICATION SERVICES │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ PDS │ │ Knot │ │ Spindle │ │ │
│ │ │ :2583 │ │ :5555 │ │ :6555 │ │ │
│ │ │ (ATProto) │ │ (Git) │ │ (CI/CD) │ │ │
│ │ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │
│ │ │ │ │ │ │
│ │ └─────────────┴─────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────┐ ┌────┴────┐ ┌───────────┐ │ │
│ │ │Spacedust │ │Slingshot│ │ Lycan │ │ │
│ │ │ :9998 │ │ :3000 │ │ :3100 │ │ │
│ │ │(Indexer) │ │ (API) │ │ (Feeds) │ │ │
│ │ └───────────┘ └─────────┘ └───────────┘ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ MONITORING LAYER │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │Prometheus │ │ Grafana │ │ Node │ │
│ │ :9090 │ │ :3001 │ │ Exporter │ │
│ │(Scrapes) │──►│(Displays) │ │ :9100 │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ EXTERNAL SERVICES │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Constella-│ │ Radicle │ │ Radicle │ │
│ │ tion │ │ P2P │ │ HTTPD │ │
│ │ (nixos) │ │ (homelab) │ │ (homelab) │ │
│ │ :6795 │ │ :8776 │ │ :8081 │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
}}}
== Network Security Zones ==
┌────────────────────────────────────────────────────────────────┐
│ INTERNET │
│ │
│ Untrusted Zone - Anyone can connect │
│ • All traffic is untrusted │
│ • Authentication at application layer │
│ • TLS encryption in transit │
│ │
│ Open Ports: 22 (SSH), 80 (HTTP), 443 (HTTPS), 8776 (Radicle) │
└────────────────────┬───────────────────────────────────────────┘
│
│ Firewall Filters
│ (Rate Limiting, IP Blocks)
▼
┌────────────────────────────────────────────────────────────────┐
│ PUBLIC SERVICES │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Caddy │ │ SSH │ │ Radicle │ │
│ │ Reverse │ │ Daemon │ │ Proxy │ │
│ │ Proxy │ │ │ │ │ │
│ └─────┬─────┘ └───────────┘ └─────┬─────┘ │
│ │ │ │
│ │ Terminates TLS │ Forwards to Tailscale │
└────────┼──────────────────────────────┼───────────────────────┘
│ │
│ ▼
│ ┌──────────────┐
│ │ Tailscale │
│ │ VPN │
│ │ (Encrypted) │
│ └──────┬───────┘
│ │
│ Semi-Trusted Zone
│ • Encrypted tunnel
│ • Authenticated devices only
│ • Your machines only
▼ │
┌─────────────────────────────────────┼──────────────────────────┐
│ LOCALHOST │ │
│ (127.0.0.1) │ │
│ │ │
│ Trusted Zone - Same machine only │ │
│ • No encryption needed │ │
│ • Services trust each other │ │
│ • Not accessible from network │ │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ PDS │ │ Knot │ │ Grafana │ │
│ │ :2583 │ │ :5555 │ │ :3001 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Spindle │ │ Lycan │ │ Prometheus│ │
│ │ :6555 │ │ :3100 │ │ :9090 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
}}}
Developer
│
│ git push knot.snek.cc:repo
│
▼
┌─────────┐ DNS ┌──────────┐
│ Git │───────────►│knot.snek.│
│ Client │ │cc → VPS │
└────┬────┘ └──────────┘
│
│ SSH over HTTPS
│
▼
┌─────────┐
│ VPS │
│ Port 443│
└────┬────┘
│
▼
┌─────────┐ Match: ┌─────────┐
│ Caddy │knot.snek.│ Tangled │
│ │cc │ Knot │
└────┬────┘ │ :5555 │
│ └────┬────┘
│ Proxy │
│ HTTP │ Git Protocol
▼ ▼
┌─────────┐ ┌─────────┐
│127.0.0.1│ │ Process │
│ :5555 │ │ Push │
└─────────┘ └────┬────┘
│
▼
┌─────────────┐
│ Update Repo │
│ /var/lib/ │
│tangled-knot/│
└─────────────┘
}}}
=== Example 2: Bluesky User Login ===
User Device
│
│ Open Bluesky App
│ Login: user@pds.snek.cc
│
▼
┌─────────────┐
│ Bluesky │
│ Client │
└──────┬──────┘
│
│ 1. Resolve DID
│ GET pds.snek.cc/.well-known/did.json
│
▼
┌─────────────┐
│ Caddy │
│ :443 │
│ (wildcard │
│ certificate)│
└──────┬──────┘
│
│ 2. Proxy to PDS
│
▼
┌─────────────┐
│ PDS │
│ :2583 │
│ │
│ 3. Verify │◄─────────┐
│ Password │ │
└──────┬──────┘ │
│ │
│ 4. Issue JWT │
│◄────────────────┘
│ Signed with
│ PDSJWTSECRET
│
▼
┌─────────────┐
│ Return │
│ Auth Token │
└─────────────┘
│
│ 5. Use Token
│ for API calls
▼
[All Future
Requests]
}}}
This architecture provides clear separation of concerns, defense in depth (multiple security layers), and horizontal scalability (services can be moved to other machines independently).