# The Nest — Documentation

Welcome to the documentation for **The Nest**, a home lab Kubernetes cluster running on three mirrored Raspberry Pi 5s. This documentation is split into two audiences:

## For Users (Accessible via `mynest.love`)

These guides explain what each service does, how to reach it, and how to get started. No technical background required.

- [Getting Started](user-facing/getting-started.md) — First-time setup, accounts, and passkeys
- [Requesting Service Access](user-facing/access-requests.md) — How to ask an admin for access to services beyond your default set
- **Media & Entertainment**
  - [Jellyfin](user-facing/media-and-entertainment/jellyfin.md) — Stream movies and TV shows
  - [Audiobookshelf](user-facing/media-and-entertainment/audiobookshelf.md) — Audiobooks and podcasts
  - [DroppedNeedle](user-facing/media-and-entertainment/droppedneedle.md) — Music discovery and streaming
  - [Calibre-Web](user-facing/media-and-entertainment/calibre-web.md) — E-book library
- **Productivity & Creation**
  - [Forgejo](user-facing/productivity-and-creation/forgejo.md) — Git hosting and code collaboration
  - [Shelfmark](user-facing/productivity-and-creation/shelfmark.md) — Track what you read and listen to
  - [Foundry VTT](user-facing/productivity-and-creation/foundry-vtt.md) — Virtual tabletop for TTRPGs
- **Storage & Files**
  - [Nextcloud](user-facing/storage-and-files/nextcloud.md) — File sync, sharing, and cloud storage
- **Communication & Security**
  - [Matrix](user-facing/communication-and-security/matrix.md) — Chat, voice/video calls, and federation
  - [Vaultwarden](user-facing/communication-and-security/vaultwarden.md) — Password manager (Bitwarden-compatible)
  - [Your Account (Keycloak)](user-facing/communication-and-security/keycloak-account.md) — Manage your identity and passkeys

## For Operators (Technical)

These documents cover architecture, networking, security, backups, and internal services. Intended for administrators and technically inclined users.

- [Architecture Overview](technical/architecture-overview.md)
- [Networking](technical/networking.md) — HAProxy, Traefik, MetalLB, ingress routing
- [Security & Identity](technical/security-and-identity.md) — Keycloak, passkeys, OIDC, group policies
- [Backups & Recovery](technical/backups-and-recovery.md) — Longhorn snapshots, Restic, schedules
- [MetalLB](technical/metallb.md) — Layer 2 load balancing for internal services
- [Vault & Keykeeper](technical/vault-and-keykeeper.md) — HashiCorp Vault HA cluster and transit sealing
- [External Secrets Operator](technical/external-secrets-operator.md) — Syncing secrets from Vault into Kubernetes
- [Longhorn Storage](technical/longhorn-storage.md) — Distributed block storage across the cluster
- [Keel & Auto-Updates](technical/keel-and-auto-updates.md) — Automated image updates for deployments
- [System Upgrade Controller](technical/system-upgrade-controller.md) — Rolling K3s upgrades
- [Monitoring Stack](technical/monitoring-stack.md) — Prometheus, Grafana, Alertmanager
- [Matrix Architecture](technical/matrix-architecture.md) — Synapse, MAS, LiveKit, and RTC internals
- [Forgejo (Technical)](technical/forgejo-technical.md) — Deployment, SSH, package registry, OIDC integration
- [Media Automation Pipeline](technical/media-automation-pipeline.md) — Sonarr, Radarr, Bazarr, Prowlarr, SABnzbd, Deluge
- [slskd (Soulseek)](technical/slskd-soulseek.md) — Peer-to-peer music sharing
- [flaresolverr](technical/flaresolverr.md) — Cloudflare bypass for indexers
- [Tadarr Transcoding](technical/tdarr-transcoding.md) — Automatic h.264 to HEVC transcoding

---

## Quick Reference: Service URLs

| Service | URL | Audience |
|---------|-----|----------|
| Jellyfin | <https://beak.mynest.love> | User |
| Audiobookshelf | <https://lyrebird.mynest.love> | User |
| DroppedNeedle | <https://heron.mynest.love> | User |
| Calibre-Web | <https://rookery.mynest.love> | User |
| Shelfmark | <https://magpie.mynest.love> | User |
| Seerr | <https://stork.mynest.love> | User |
| Nextcloud | <https://cloud.mynest.love> | User |
| Vaultwarden | <https://vault.mynest.love> | User |
| Forgejo | <https://weaver.mynest.love> | User |
| Matrix (Synapse) | <https://starling.mynest.love> | User |
| Matrix RTC | <https://matrix-rtc.mynest.love> | User |
| Keycloak (SSO) | <https://sso.mynest.love> | User |
| Foundry VTT | <https://foundry.mynest.love> | User |

---

## Conventions

- All user-facing services use TLS certificates issued by [Let's Encrypt](https://letsencrypt.org/) via cert-manager.
- Internal-only services (media automation, Soulseek, etc.) are reachable only within the home network at `*.k3s.home.nest`.
- Non-critical services auto-update daily around 03:00 EST. Brief disruptions may occur.
- Nest host OSes update weekly on Sundays at 05:00 EST in a rolling fashion.

---

*This documentation is maintained as code. If you spot an error or have a suggestion, open an issue or reach out via Matrix.*