first commit

README.md

@@ -0,0 +1,91 @@
+# Homelab
+
+> Infrastructure documentation, Ansible configs, and runbooks for my homelab.
+
+## Quick Links
+
+| | |
+|---|---|
+| 🗺️ [Network Topology](docs/network/topology.md) | IP map, VLANs, DNS |
+| 🖥️ [Hosts](docs/hosts/) | Per-machine reference |
+| ⚙️ [Services](docs/services/) | Per-service reference |
+| 📖 [Runbooks](docs/runbooks/) | Step-by-step procedures |
+| 🗓️ [Decision Log](docs/decisions/) | Why things are the way they are |
+
+---
+
+## Hosts at a Glance
+
+| Hostname | Role | IP | OS |
+|---|---|---|---|
+| `proxmox-main` | Primary Proxmox node, arr stack, Jellyfin | `192.168.x.x` | Proxmox VE |
+| `pbs` | Proxmox Backup Server (HP MicroServer Gen8) | `192.168.x.x` | PBS |
+| `optiplex-3020` | Networking/proxy services | `192.168.x.x` | Proxmox VE |
+| `optiplex-3070` | Stateful services | `192.168.x.x` | Proxmox VE |
+
+> Update this table as hosts are added or change role.
+
+---
+
+## Services at a Glance
+
+| Service | Host | Port | Notes |
+|---|---|---|---|
+| Jellyfin | `proxmox-main` | `8096` | |
+| WireGuard | `optiplex-3020` | `51820/udp` | |
+| Vaultwarden | `optiplex-3020` | `8080` | |
+| Reverse Proxy | `optiplex-3020` | `80/443` | |
+
+---
+
+## Repo Layout
+
+```
+homelab/
+├── ansible/          # Inventory, playbooks, roles
+├── docker/           # Docker Compose configs per service
+├── docs/             # This documentation
+│   ├── hosts/
+│   ├── services/
+│   ├── network/
+│   ├── runbooks/
+│   └── decisions/
+└── .gitea/workflows/ # CI/CD pipelines
+```
+
+---
+
+## Common Tasks
+
+```bash
+# Run full site playbook (safe to re-run anytime)
+make deploy
+
+# Bootstrap a brand-new machine
+make bootstrap HOST=optiplex-3070
+
+# Dry-run to preview changes
+make check
+
+# Lint Ansible
+make lint
+```
+
+---
+
+## Secrets
+
+Secrets are **never committed**. Use `.env.example` files as templates. Sensitive Ansible vars are encrypted with Ansible Vault.
+
+```bash
+# Edit a vault-encrypted file
+ansible-vault edit ansible/group_vars/all/vault.yml
+```
+
+---
+
+## Contributing / Updating
+
+- Update the relevant doc **before** making infrastructure changes
+- Keep the hosts/services tables above in sync
+- Log significant decisions in `docs/decisions/` with today's date