"vault backup: 2026-03-08 13:41:28 from Flow"
This commit is contained in:
@@ -1,50 +1,88 @@
|
||||
# Homelab Server Documentation
|
||||
# Server Reference
|
||||
|
||||
Living documentation for the `homelab` server. Goal: a new admin with zero prior context should be able to read this and understand everything about the server.
|
||||
Documentation for the home infrastructure — two servers working together.
|
||||
|
||||
## Quick Reference
|
||||
## Servers
|
||||
|
||||
| Property | Value |
|
||||
| Server | Role | Docs |
|
||||
| ------------------------- | ---------------------------------------------------------- | ------------------ |
|
||||
| **Homelab** | Primary server. Runs most services. | [[homelab/README]] |
|
||||
| **Pihole / Raspberry Pi** | Secondary server. DNS, Home Assistant, Tailscale bridging. | [[pihole/README]] |
|
||||
|
||||
---
|
||||
|
||||
## Tailscale Sidecar Setup
|
||||
|
||||
The standard pattern for exposing a service via Tailscale. Used across nearly every stack.
|
||||
|
||||
1. Create your service container and a Tailscale sidecar container
|
||||
2. On the sidecar, set:
|
||||
```yaml
|
||||
network_mode: "service:[service-name]"
|
||||
```
|
||||
3. Connect to the sidecar via SSH or the Tailscale admin console and run:
|
||||
```
|
||||
tailscale funnel --bg [port]
|
||||
```
|
||||
|
||||
The sidecar shares the main container's network namespace, so Tailscale sees the service's ports as its own.
|
||||
|
||||
---
|
||||
|
||||
## Credentials & Tokens
|
||||
|
||||
> These are stored here for admin reference. Do not share.
|
||||
|
||||
### Mealie
|
||||
| Key | Value |
|
||||
|---|---|
|
||||
| Hostname | `homelab` |
|
||||
| LAN IP | `192.168.2.114` |
|
||||
| Tailscale IP | `100.72.0.62` |
|
||||
| OS | Ubuntu 25.10 (Questing Quokka) |
|
||||
| Kernel | 6.17.0-14-generic |
|
||||
| Docker Files | `/home/artanis/DockerFiles/` |
|
||||
| Docker Manager | [dockhand.bunny-wyvern.ts.net](https://dockhand.bunny-wyvern.ts.net) |
|
||||
| Auth Token | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb25nX3Rva2VuIjp0cnVlLCJpZCI6IjNkZjZkZmM0LTkyZDgtNDIyNy1iMjBjLTA4ZjA2Njc2MGcă0IsIm5hbWUiOiJMTE0gIiwiaW50ZWdyYXRpb25faWQiOiJnZW5lcmljIiwiZXhwIjoxOTE5OTEwNDUwfQ.Ts5XbrF6Nr-0gvhKkt_01OPeAEoWQe_ndn0hGTtPOQc` |
|
||||
|
||||
## Documentation Index
|
||||
### Discord Bots
|
||||
| Bot | Token |
|
||||
|---|---|
|
||||
| Isomer | `NjY0MjMyOTYxMjM4ODkyNTc0.XhUFJg.ivnkBPtnEPGGcAwaXP50rOIPZsI` |
|
||||
| Star-15 | `ODQ2MTUxMDMxMjA1MDAzMjc0.GYFbRW.JeFITOZbBH_lqCuF-bS7edC0P30H6uqFKwz7is` |
|
||||
|
||||
- [[hardware]] — CPU, RAM, storage
|
||||
- [[network]] — Interfaces, Tailscale, ports in use
|
||||
- [[environments]] — Dockhand-managed environments (Homelab + Pihole)
|
||||
- [[stacks/README]] — Overview of all Docker stacks
|
||||
### AI
|
||||
| Service | Key |
|
||||
|---|---|
|
||||
| Gemini API | `AIzaSyD0uj33T_SH4Fvw2sWWW9akXF6ej9sqhlI` |
|
||||
|
||||
### Stacks
|
||||
| Stack | Purpose | Access |
|
||||
|---|---|---|
|
||||
| [[stacks/dockhand]] | Docker management UI | [dockhand.bunny-wyvern.ts.net](https://dockhand.bunny-wyvern.ts.net) |
|
||||
| [[stacks/minecraft]] | Minecraft server (TerraFirmaGreg) | `:25565` |
|
||||
| [[stacks/mealie]] | Recipe manager | [mealie.bunny-wyvern.ts.net](https://mealie.bunny-wyvern.ts.net) |
|
||||
| [[stacks/linkwarden]] | Bookmark manager | [linkwarden.bunny-wyvern.ts.net](https://linkwarden.bunny-wyvern.ts.net) |
|
||||
| [[stacks/gitea]] | Self-hosted Git | [gitea.bunny-wyvern.ts.net](https://gitea.bunny-wyvern.ts.net) |
|
||||
| [[stacks/matrix]] | Matrix homeserver + bridges | [matrix.bunny-wyvern.ts.net](https://matrix.bunny-wyvern.ts.net) |
|
||||
| [[stacks/homepage]] | Dashboard | [homepage.bunny-wyvern.ts.net](https://homepage.bunny-wyvern.ts.net) |
|
||||
| [[stacks/n8n]] | Workflow automation | [n8n.bunny-wyvern.ts.net](https://n8n.bunny-wyvern.ts.net) |
|
||||
| [[stacks/calibre]] | E-book library (STOPPED) | [calibre.bunny-wyvern.ts.net](https://calibre.bunny-wyvern.ts.net) |
|
||||
| [[stacks/gluetun]] | VPN gateway (Mullvad) | `:8001` (control) |
|
||||
| [[stacks/openproject]] | Project management | [openproject.bunny-wyvern.ts.net](https://openproject.bunny-wyvern.ts.net) |
|
||||
| [[stacks/melodix]] | Discord music bot | Internal only |
|
||||
### Server Passwords
|
||||
Shared password used across most Docker services (DB passwords, NextAuth secrets, etc.): see compose files at `/home/artanis/DockerFiles/` on the homelab.
|
||||
|
||||
## Key Architectural Patterns
|
||||
---
|
||||
|
||||
### Tailscale Sidecar
|
||||
Nearly every service uses a **Tailscale sidecar** pattern for remote access:
|
||||
- A `tailscale/tailscale` container runs alongside the main service container
|
||||
- It uses `network_mode: "service:[main]"` to share the main container's network namespace
|
||||
- This registers the main service as a Tailscale node (e.g. `mealie.bunny-wyvern.ts.net`)
|
||||
- Services are **not exposed to the public internet** — only accessible via Tailscale VPN
|
||||
## File Index
|
||||
|
||||
### Credentials
|
||||
Credentials (DB passwords, API keys, Tailscale auth keys) live in the compose files on disk at `/home/artanis/DockerFiles/`. They are redacted in this documentation. See individual stack files for variable names and the actual compose files for values.
|
||||
```
|
||||
21-Server Reference/
|
||||
├── README.md ← You are here
|
||||
├── Server Info.md ← Legacy notes (superseded by this file)
|
||||
├── homelab/
|
||||
│ ├── README.md — Homelab overview & stack index
|
||||
│ ├── hardware.md — CPU, RAM, storage
|
||||
│ ├── network.md — IPs, ports, Tailscale nodes, Docker networks
|
||||
│ ├── environments.md — Dockhand environments (Homelab + Pihole)
|
||||
│ └── stacks/
|
||||
│ ├── README.md — All stacks at a glance
|
||||
│ ├── dockhand.md
|
||||
│ ├── minecraft.md
|
||||
│ ├── mealie.md
|
||||
│ ├── linkwarden.md
|
||||
│ ├── gitea.md
|
||||
│ ├── matrix.md
|
||||
│ ├── homepage.md
|
||||
│ ├── n8n.md
|
||||
│ ├── calibre.md
|
||||
│ ├── gluetun.md
|
||||
│ ├── openproject.md
|
||||
│ └── melodix.md
|
||||
└── pihole/
|
||||
├── README.md — Pi overview
|
||||
└── stacks/
|
||||
├── home_assistant.md
|
||||
├── ts_kh_bridge.md
|
||||
└── portainer_agent.md
|
||||
```
|
||||
|
||||
50
21-Server Reference/homelab/README.md
Normal file
50
21-Server Reference/homelab/README.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Homelab Server Documentation
|
||||
|
||||
Living documentation for the `homelab` server. Goal: a new admin with zero prior context should be able to read this and understand everything about the server.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Hostname | `homelab` |
|
||||
| LAN IP | `192.168.2.114` |
|
||||
| Tailscale IP | `100.72.0.62` |
|
||||
| OS | Ubuntu 25.10 (Questing Quokka) |
|
||||
| Kernel | 6.17.0-14-generic |
|
||||
| Docker Files | `/home/artanis/DockerFiles/` |
|
||||
| Docker Manager | [dockhand.bunny-wyvern.ts.net](https://dockhand.bunny-wyvern.ts.net) |
|
||||
|
||||
## Documentation Index
|
||||
|
||||
- [[hardware]] — CPU, RAM, storage
|
||||
- [[network]] — Interfaces, Tailscale, ports in use
|
||||
- [[environments]] — Dockhand-managed environments (Homelab + Pihole)
|
||||
- [[stacks/README]] — Overview of all Docker stacks
|
||||
|
||||
### Stacks
|
||||
| Stack | Purpose | Access |
|
||||
|---|---|---|
|
||||
| [[stacks/dockhand]] | Docker management UI | [dockhand.bunny-wyvern.ts.net](https://dockhand.bunny-wyvern.ts.net) |
|
||||
| [[stacks/minecraft]] | Minecraft server (TerraFirmaGreg) | `:25565` |
|
||||
| [[stacks/mealie]] | Recipe manager | [mealie.bunny-wyvern.ts.net](https://mealie.bunny-wyvern.ts.net) |
|
||||
| [[stacks/linkwarden]] | Bookmark manager | [linkwarden.bunny-wyvern.ts.net](https://linkwarden.bunny-wyvern.ts.net) |
|
||||
| [[stacks/gitea]] | Self-hosted Git | [gitea.bunny-wyvern.ts.net](https://gitea.bunny-wyvern.ts.net) |
|
||||
| [[stacks/matrix]] | Matrix homeserver + bridges | [matrix.bunny-wyvern.ts.net](https://matrix.bunny-wyvern.ts.net) |
|
||||
| [[stacks/homepage]] | Dashboard | [homepage.bunny-wyvern.ts.net](https://homepage.bunny-wyvern.ts.net) |
|
||||
| [[stacks/n8n]] | Workflow automation | [n8n.bunny-wyvern.ts.net](https://n8n.bunny-wyvern.ts.net) |
|
||||
| [[stacks/calibre]] | E-book library (STOPPED) | [calibre.bunny-wyvern.ts.net](https://calibre.bunny-wyvern.ts.net) |
|
||||
| [[stacks/gluetun]] | VPN gateway (Mullvad) | `:8001` (control) |
|
||||
| [[stacks/openproject]] | Project management | [openproject.bunny-wyvern.ts.net](https://openproject.bunny-wyvern.ts.net) |
|
||||
| [[stacks/melodix]] | Discord music bot | Internal only |
|
||||
|
||||
## Key Architectural Patterns
|
||||
|
||||
### Tailscale Sidecar
|
||||
Nearly every service uses a **Tailscale sidecar** pattern for remote access:
|
||||
- A `tailscale/tailscale` container runs alongside the main service container
|
||||
- It uses `network_mode: "service:[main]"` to share the main container's network namespace
|
||||
- This registers the main service as a Tailscale node (e.g. `mealie.bunny-wyvern.ts.net`)
|
||||
- Services are **not exposed to the public internet** — only accessible via Tailscale VPN
|
||||
|
||||
### Credentials
|
||||
Credentials (DB passwords, API keys, Tailscale auth keys) live in the compose files on disk at `/home/artanis/DockerFiles/`. They are redacted in this documentation. See individual stack files for variable names and the actual compose files for values.
|
||||
35
21-Server Reference/pihole/README.md
Normal file
35
21-Server Reference/pihole/README.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Pihole / Raspberry Pi Documentation
|
||||
|
||||
Secondary server — a Raspberry Pi that supports the main [[../homelab/README|homelab]] in various ways.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Tailscale IP | `100.89.172.56` |
|
||||
| Tailscale Hostname | (on `bunny-wyvern.ts.net`) |
|
||||
| Connection to Dockhand | Hawser agent (env=2) |
|
||||
| Docker Files | `/home/artanis/` (Desktop + TS_KH_Bridge dirs) |
|
||||
|
||||
> Hardware details (CPU, RAM, model) are not yet documented. To be filled in.
|
||||
|
||||
## Stacks
|
||||
|
||||
| Stack | Status | Purpose |
|
||||
|---|---|---|
|
||||
| [[stacks/home_assistant]] | Running | Home automation |
|
||||
| [[stacks/ts_kh_bridge]] | Stopped | Tailscale inter-tailnet bridge |
|
||||
| [[stacks/portainer_agent]] | Running | Portainer remote agent |
|
||||
|
||||
## How It Supports the Homelab
|
||||
|
||||
- **Home Assistant** — Home automation hub; runs on the Pi for low-power always-on operation and USB device access (Zigbee/Z-Wave stick on `/dev/ttyUSB0`)
|
||||
- **Tailscale Bridge** — Bridges two separate Tailnets together (`Home` ↔ `KH`) — currently stopped
|
||||
- **Portainer Agent** — Allows a Portainer instance (elsewhere) to manage this Pi's Docker remotely
|
||||
|
||||
## Key Differences from Homelab
|
||||
|
||||
- No centralized `DockerFiles` directory — compose files are scattered across `~/Desktop/` and `~/TS_KH_Bridge/`
|
||||
- Home Assistant uses `network_mode: host` (full host network) for mDNS/Bluetooth/Zigbee discovery
|
||||
- Much lighter workload — only 3 stacks, 5 containers total
|
||||
- Pihole (DNS/ad-blocking) likely runs natively on the Pi OS, not in Docker — no container found for it
|
||||
85
21-Server Reference/pihole/stacks/home_assistant.md
Normal file
85
21-Server Reference/pihole/stacks/home_assistant.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Home Assistant
|
||||
|
||||
Self-hosted home automation platform. The primary reason this Pi exists.
|
||||
|
||||
## Access
|
||||
- **Tailscale:** [homeassistant.bunny-wyvern.ts.net](https://homeassistant.bunny-wyvern.ts.net)
|
||||
- **LAN:** `http://[pi-ip]:8123` (port exposed but access via Tailscale preferred)
|
||||
|
||||
## Containers
|
||||
|
||||
| Container | Image | Role |
|
||||
|---|---|---|
|
||||
| `homeassistant` | `lscr.io/linuxserver/homeassistant:latest` | Home automation hub |
|
||||
| `homeassistant-tailscale-sidecar` | `tailscale/tailscale:latest` | Tailscale node |
|
||||
|
||||
## Compose File
|
||||
**Path:** `/home/artanis/Desktop/HomeAssistant/docker-compose.yaml` (on the Pi)
|
||||
|
||||
> Note: Dockhand reports the stack dir as `/DockerFiles/home_assistant/` — this is the path as seen from inside the Hawser agent context. The actual host path is via `~/Desktop/HomeAssistant/`.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
homeassistant:
|
||||
image: lscr.io/linuxserver/homeassistant:latest
|
||||
container_name: homeassistant
|
||||
network_mode: host
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
- TZ: America/Chicago
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
- NET_RAW
|
||||
volumes:
|
||||
- /home/artanis/Desktop/HomeAssistant/config:/config
|
||||
- /run/dbus:/run/dbus:ro
|
||||
- /home/artanis/Desktop/HomeAssistant/media:/media
|
||||
ports:
|
||||
- 8123:8123
|
||||
devices:
|
||||
- /dev/ttyUSB0:/dev/ttyUSB0
|
||||
restart: unless-stopped
|
||||
|
||||
homeassistant-tailscale-sidecar:
|
||||
image: tailscale/tailscale:latest
|
||||
container_name: homeassistant-tailscale-sidecar
|
||||
restart: unless-stopped
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
devices:
|
||||
- /dev/net/tun
|
||||
volumes:
|
||||
- homeassistant_tailscale_state:/var/lib/tailscale
|
||||
environment:
|
||||
- TS_AUTHKEY=<redacted>
|
||||
- TS_HOSTNAME=homeassistant
|
||||
- TS_STATE_DIR=/var/lib/tailscale
|
||||
network_mode: "service:homeassistant"
|
||||
|
||||
volumes:
|
||||
homeassistant_tailscale_state:
|
||||
|
||||
# matter-server is defined but commented out
|
||||
```
|
||||
|
||||
## Data Layout
|
||||
|
||||
| Path | Contents |
|
||||
|---|---|
|
||||
| `/home/artanis/Desktop/HomeAssistant/config` | HA configuration, automations, integrations |
|
||||
| `/home/artanis/Desktop/HomeAssistant/media` | Media files for HA |
|
||||
| `/run/dbus` | Host D-Bus socket (read-only, for Bluetooth) |
|
||||
|
||||
## Hardware Devices
|
||||
|
||||
| Device | Purpose |
|
||||
|---|---|
|
||||
| `/dev/ttyUSB0` | USB serial device — likely a Zigbee or Z-Wave stick |
|
||||
|
||||
## Notes
|
||||
- `network_mode: host` — Home Assistant runs on the Pi's full host network. This is required for mDNS/Bonjour device discovery, Bluetooth, and multicast protocols that don't work through Docker's bridge NAT
|
||||
- `cap_add: NET_ADMIN, NET_RAW` — required for network-level features (e.g. ping, ARP for device tracking)
|
||||
- `/run/dbus` is mounted read-only for Bluetooth integration via D-Bus
|
||||
- **Matter server** is fully defined in the compose file but commented out — can be enabled when needed
|
||||
- There is an orphaned volume `homeassistant_homeassistant_tailscale_state` from an earlier stack iteration (project was named `homeassistant` instead of `home_assistant`)
|
||||
26
21-Server Reference/pihole/stacks/portainer_agent.md
Normal file
26
21-Server Reference/pihole/stacks/portainer_agent.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Portainer Agent
|
||||
|
||||
Lightweight Portainer remote agent that allows a Portainer server instance to manage this Pi's Docker remotely.
|
||||
|
||||
## Access
|
||||
- **Port:** `9001` (TCP) — Portainer server connects to this
|
||||
|
||||
## Containers
|
||||
|
||||
| Container | Image | Role |
|
||||
|---|---|---|
|
||||
| `portainer_agent` | `portainer/agent:latest` | Remote Docker management agent |
|
||||
|
||||
## Compose File
|
||||
**Path:** `/home/artanis/Desktop/Portainer_Agent/docker-compose.yml` (on the Pi)
|
||||
|
||||
> Dockhand reports the compose location as unknown (`needsFileLocation: true`). Path inferred from container labels.
|
||||
|
||||
Compose content not available via API. Key details from container labels and mounts:
|
||||
- Mounts `/var/lib/docker/volumes` and `/var/run/docker.sock` into the agent container
|
||||
- Exposes port `9001` on all interfaces
|
||||
|
||||
## Notes
|
||||
- No Portainer server is currently running in Docker on either the homelab or this Pi (the `portainer` stack on the homelab has no containers and is in `created` state)
|
||||
- This agent is likely a leftover from a previous setup, or is intended to connect to a Portainer server instance not yet deployed
|
||||
- The agent has full access to the Pi's Docker socket and volumes — it should only be reachable by a trusted Portainer server
|
||||
39
21-Server Reference/pihole/stacks/ts_kh_bridge.md
Normal file
39
21-Server Reference/pihole/stacks/ts_kh_bridge.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Tailscale KH Bridge
|
||||
|
||||
A Tailscale inter-tailnet bridge — connects two separate Tailscale networks together so devices on each tailnet can reach each other.
|
||||
|
||||
**Status: STOPPED** — Both containers exited cleanly (exit code 0) approximately 14 hours before this was documented.
|
||||
|
||||
## Containers
|
||||
|
||||
| Container | Image | Role |
|
||||
|---|---|---|
|
||||
| `Home_Bridge` | `tailscale/tailscale:latest` | Node on the "Home" tailnet |
|
||||
| `KH_Bridge` | `tailscale/tailscale:latest` | Node on the "KH" tailnet |
|
||||
|
||||
Both containers are on a shared bridge network (`ts_kh_bridge_tailnet-interlink`, `172.20.0.0/24`) so they can route traffic between each other.
|
||||
|
||||
## Compose File
|
||||
**Path:** `/home/artanis/TS_KH_Bridge/docker-compose.yaml` (on the Pi)
|
||||
|
||||
> Dockhand reports this stack's compose location as unknown (`needsFileLocation: true`) — the path was inferred from container labels.
|
||||
|
||||
Compose content not available via API. Key details from container labels:
|
||||
|
||||
| Property | Home_Bridge | KH_Bridge |
|
||||
|---|---|---|
|
||||
| Service name | `home-bridge` | `kh-bridge` |
|
||||
| Tailscale state | `/home/artanis/TS_KH_Bridge/home_state` (bind mount) | `/home/artanis/TS_KH_Bridge/kh_state` (bind mount) |
|
||||
| `/dev/net/tun` | Bind-mounted | Bind-mounted |
|
||||
|
||||
## How It Works
|
||||
|
||||
Tailscale supports bridging two separate tailnets by running two Tailscale nodes on the same machine — one registered to each tailnet — and routing traffic between them. The two containers share a Docker bridge network (`tailnet-interlink`) which acts as the routing path between the two tailnet nodes.
|
||||
|
||||
- `Home_Bridge` — authenticated to the primary (`bunny-wyvern.ts.net`) tailnet
|
||||
- `KH_Bridge` — authenticated to a second tailnet ("KH")
|
||||
|
||||
## Notes
|
||||
- Both containers use **bind-mounted** Tailscale state directories (not named volumes), so state survives container recreation as long as the host paths exist
|
||||
- The stack exited cleanly (code 0), suggesting it was intentionally stopped rather than crashed
|
||||
- To restart: `docker compose up -d` in `/home/artanis/TS_KH_Bridge/`
|
||||
Reference in New Issue
Block a user