# 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