From 9b2c6301ee78834a0ff7c0a1358415b216b62ee8 Mon Sep 17 00:00:00 2001 From: KnightArtorias Date: Thu, 23 Jul 2026 18:24:39 -0400 Subject: [PATCH] AI-genned docs --- IdentityFile ~/.ssh/your-key | 22 +++++ documentation/README.md | 80 +++++++++++++++++++ context.txt => documentation/context.txt | 0 .../technical/architecture-overview.md | 6 ++ documentation/technical/networking.md | 64 +++++++++++++++ .../technical/security-and-identity.md | 57 +++++++++++++ documentation/user-facing/access-requests.md | 16 ++++ .../keycloak-account.md | 59 ++++++++++++++ .../communication-and-security/matrix.md | 56 +++++++++++++ .../communication-and-security/vaultwarden.md | 51 ++++++++++++ documentation/user-facing/getting-started.md | 54 +++++++++++++ .../media-and-entertainment/audiobookshelf.md | 42 ++++++++++ .../media-and-entertainment/calibre-web.md | 49 ++++++++++++ .../media-and-entertainment/droppedneedle.md | 46 +++++++++++ .../media-and-entertainment/jellyfin.md | 48 +++++++++++ .../user-facing/media-request/seerr.md | 44 ++++++++++ .../productivity-and-creation/forgejo.md | 38 +++++++++ .../productivity-and-creation/foundry-vtt.md | 42 ++++++++++ .../productivity-and-creation/shelfmark.md | 46 +++++++++++ .../storage-and-files/nextcloud.md | 61 ++++++++++++++ 20 files changed, 881 insertions(+) create mode 100644 IdentityFile ~/.ssh/your-key create mode 100644 documentation/README.md rename context.txt => documentation/context.txt (100%) create mode 100644 documentation/technical/architecture-overview.md create mode 100644 documentation/technical/networking.md create mode 100644 documentation/technical/security-and-identity.md create mode 100644 documentation/user-facing/access-requests.md create mode 100644 documentation/user-facing/communication-and-security/keycloak-account.md create mode 100644 documentation/user-facing/communication-and-security/matrix.md create mode 100644 documentation/user-facing/communication-and-security/vaultwarden.md create mode 100644 documentation/user-facing/getting-started.md create mode 100644 documentation/user-facing/media-and-entertainment/audiobookshelf.md create mode 100644 documentation/user-facing/media-and-entertainment/calibre-web.md create mode 100644 documentation/user-facing/media-and-entertainment/droppedneedle.md create mode 100644 documentation/user-facing/media-and-entertainment/jellyfin.md create mode 100644 documentation/user-facing/media-request/seerr.md create mode 100644 documentation/user-facing/productivity-and-creation/forgejo.md create mode 100644 documentation/user-facing/productivity-and-creation/foundry-vtt.md create mode 100644 documentation/user-facing/productivity-and-creation/shelfmark.md create mode 100644 documentation/user-facing/storage-and-files/nextcloud.md diff --git a/IdentityFile ~/.ssh/your-key b/IdentityFile ~/.ssh/your-key new file mode 100644 index 0000000..e6631b1 --- /dev/null +++ b/IdentityFile ~/.ssh/your-key @@ -0,0 +1,22 @@ + +## Package Registry + +Forgejo includes a package registry for sharing binaries, Docker images, and other artifacts: + +- **Docker:** `docker pull weaver.mynest.love/nest/your-image:tag` +- **npm/go/python:** Configure your package manager to authenticate with your Forgejo token (generate one under **Settings → Applications → Generate Token**). + +## Tips + +- **Two-factor auth:** While passkeys handle SSO, enable 2FA in Forgejo settings for an extra layer of security on the git server itself. +- **Actions:** Use `.forgejo/workflows/` in your repo to define CI pipelines (compatible with GitHub Actions syntax). +- **Webhooks:** Set up webhooks to trigger external services when you push code. + +## Related Services + +- [Semaphore](https://semaphore.k3s.home.nest) — Ansible automation UI for infrastructure management +- [Keycloak](../technical/security-and-identity.md) — Powers SSO and group-based access control + +--- + +*TODO: Add screenshot of Forgejo repository view with a sample project.* diff --git a/documentation/README.md b/documentation/README.md new file mode 100644 index 0000000..32b7d0a --- /dev/null +++ b/documentation/README.md @@ -0,0 +1,80 @@ +# 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 | | User | +| Audiobookshelf | | User | +| DroppedNeedle | | User | +| Calibre-Web | | User | +| Shelfmark | | User | +| Seerr | | User | +| Nextcloud | | User | +| Vaultwarden | | User | +| Forgejo | | User | +| Matrix (Synapse) | | User | +| Matrix RTC | | User | +| Keycloak (SSO) | | User | +| Foundry VTT | | 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.* diff --git a/context.txt b/documentation/context.txt similarity index 100% rename from context.txt rename to documentation/context.txt diff --git a/documentation/technical/architecture-overview.md b/documentation/technical/architecture-overview.md new file mode 100644 index 0000000..8f5565e --- /dev/null +++ b/documentation/technical/architecture-overview.md @@ -0,0 +1,6 @@ +# Architecture Overview + +The Nest is a high-availability Kubernetes cluster running [k3s](https://k3s.io/) on three mirrored Raspberry Pi 5 nodes. The architecture prioritizes resilience, security, and ease of maintenance for both the admin and end users. + +## Topology + diff --git a/documentation/technical/networking.md b/documentation/technical/networking.md new file mode 100644 index 0000000..c711dfe --- /dev/null +++ b/documentation/technical/networking.md @@ -0,0 +1,64 @@ +# Networking + +The Nest's networking stack handles external ingress (from the internet), internal routing (between services), and load balancing for services that require public IP addresses. + +## External Ingress: HAProxy on pfSense + +All traffic from the internet enters through an [HAProxy](https://www.haproxy.org/) instance running on the pfSense router. HAProxy performs: + +- **TLS termination** — Handles SSL certificates for all `*.mynest.love` domains +- **Hostname-based routing** — Forwards requests to the appropriate internal service based on the `Host` header +- **Health checks** — Monitors backend availability and fails over if a node is down + +HAProxy routes traffic to MetalLB-assigned IPs within the cluster, which then forward to Traefik ingress controllers. + +## Internal Ingress: Traefik + +[Traefik](https://traefik.io/) is the Kubernetes-native ingress controller. It receives traffic from HAProxy and routes it to the correct service based on: + +- **Host headers** (e.g., `beak.mynest.love` → Jellyfin) +- **Path prefixes** (e.g., `/_matrix/...` → Synapse, `/sfu/get` → LiveKit JWT service) +- **Middleware annotations** for headers, redirects, and TLS enforcement + +Traefik is configured via Kubernetes CRDs (`Ingress`, `Middleware`) defined in YAML files under `services/*/`. + +## Load Balancing: MetalLB + +[MetalLB](https://metallb.io/) provides Layer 2 load balancing for services that need a public IP (e.g., Matrix LiveKit's UDP ports, Forgejo SSH). + +### Configuration + +- **IP Pool:** `192.168.1.150`–`192.168.1.200` (defined in `metallb/metallb.yaml`) +- **Advertisement Protocol:** L2 (ARP) — suitable for home networks without BGP support + +### Services Using MetalLB + +| Service | IP Assignment | Purpose | +|---------|--------------|---------| +| LiveKit (Matrix RTC) | `192.168.1.160` | WebRTC media relay (UDP/TCP) | +| Forgejo SSH | Load-balanced | Git over SSH (port 22) | + +## DNS & Hostname Resolution + +- **External:** The `*.mynest.love` domain points to the pfSense router's public IP. HAProxy handles virtual hosting. +- **Internal:** Services resolve via Kubernetes DNS (`..svc.cluster.local`). External hostnames (e.g., `robin.home.nest`) are resolved via the home network's DNS server. + +## TLS & Certificates + +All external-facing services use TLS certificates issued by [Let's Encrypt](https://letsencrypt.org/) via cert-manager: + +- **Cluster Issuer:** `letsencrypt-prod` (defined in `cert-manager/letsencrypt-cluster-issuer.yaml`) +- **Challenge Type:** HTTP-01 (validated through Traefik) +- **Auto-renewal:** Handled automatically by cert-manager 30 days before expiry + +Internal-only services (e.g., `*.k3s.home.nest`) may use self-signed certificates or no TLS, depending on the service configuration. + +## Network Policies + +The cluster does not enforce strict network policies between namespaces by default. Services communicate freely within the cluster via Kubernetes DNS and ClusterIP services. For enhanced security, consider implementing [Kubernetes NetworkPolicies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) in future iterations. + +## Related Documentation + +- [MetalLB](metallb.md) — Detailed MetalLB configuration +- [Security & Identity](security-and-identity.md) — TLS termination and authentication flow +- [Architecture Overview](architecture-overview.md) — High-level data flow diff --git a/documentation/technical/security-and-identity.md b/documentation/technical/security-and-identity.md new file mode 100644 index 0000000..1d8b2e4 --- /dev/null +++ b/documentation/technical/security-and-identity.md @@ -0,0 +1,57 @@ +# Security & Identity + +The Nest's security model is built around three pillars: **identity management** (Keycloak), **secrets management** (Vault), and **network security** (TLS, MetalLB, Traefik middleware). + +## Identity: Keycloak + +[Keycloak](https://keycloak.org/) is the central identity provider for all user-facing services. It handles authentication, authorization, and single sign-on (SSO) via OpenID Connect (OIDC). + +### Configuration + +- **Namespace:** `security` +- **Image:** `quay.io/keycloak/keycloak:latest` +- **Hostname:** `sso.mynest.love` +- **Database:** PostgreSQL (`keycloak-postgres.security.svc.cluster.local`) +- **Proxy Headers:** `xforwarded` (required behind HAProxy) + +### Authentication Flow + +1. User visits a service (e.g., Jellyfin). +2. Service redirects to Keycloak's OIDC authorization endpoint. +3. User authenticates via **WebAuthn passkey** (passwordless). +4. Keycloak issues an ID token and access token. +5. Service validates the token and grants access based on group membership. + +### Passkeys (WebAuthn) + +- All authentication is **passwordless** after initial setup. +- Users enroll passkeys on their devices (smartphone, security key, etc.). +- Passkeys are stored in Keycloak's `webauthn` credential store. +- Account recovery requires admin intervention + email verification. + +### Group-Based Authorization + +Access to services is controlled by Keycloak groups: + +| Group | Services Unlocked | +|-------|-------------------| +| (default) | Matrix, Vaultwarden, Forgejo, Documentation | +| `media-users` | Jellyfin, Sonarr, Radarr, Bazarr | +| `music-users` | DroppedNeedle, slskd | +| `books-users` | Calibre-Web, Shelfmark, Audiobookshelf | +| `storage-users` | Nextcloud | +| `ttrpg-users` | Foundry VTT | + +Groups are managed by an admin. Users request access via the Matrix bot (`@access-bot:starling.mynest.love`). + +### Related Documentation + +- [Keycloak (Technical)](keycloak-technical.md) — Deep dive into Keycloak configuration +- [Matrix Architecture](matrix-architecture.md) — How MAS integrates with Keycloak + +## Secrets Management: HashiCorp Vault + +[HashiCorp Vault](https://www.vaultproject.io/) manages secrets for all services. It is deployed as a 3-node Raft cluster with transit sealing via [Keykeeper](vault-and-keykeeper.md). + +### Architecture + diff --git a/documentation/user-facing/access-requests.md b/documentation/user-facing/access-requests.md new file mode 100644 index 0000000..d3706b6 --- /dev/null +++ b/documentation/user-facing/access-requests.md @@ -0,0 +1,16 @@ +# Requesting Service Access + +By default, new users are granted access to **Matrix**, **Vaultwarden**, **Forgejo**, and this documentation site. All other services require an admin to approve your request via Keycloak group membership. + +## How to Request Access + +Access is managed through a Matrix bot. Follow these steps: + +### 1. Open a Chat with the Bot + +Send a direct message to `@access-bot:starling.mynest.love` on Matrix. If you don't see it, search for **Nest Access Bot** in your contacts. + +### 2. List Available Groups + +Send the command: + diff --git a/documentation/user-facing/communication-and-security/keycloak-account.md b/documentation/user-facing/communication-and-security/keycloak-account.md new file mode 100644 index 0000000..23ae5fc --- /dev/null +++ b/documentation/user-facing/communication-and-security/keycloak-account.md @@ -0,0 +1,59 @@ +# Your Account (Keycloak) — Identity & Passkeys + +Your identity on The Nest is managed by [Keycloak](https://keycloak.org/), an open-source identity and access management platform. Keycloak handles authentication, passkeys, and group-based authorization for all services. + +## What Keycloak Does + +- **Authentication:** Verifies your identity using WebAuthn passkeys (passwordless). +- **Authorization:** Determines which services you can access based on your Keycloak groups. +- **Single Sign-On (SSO):** One login grants access to all connected services (Matrix, Forgejo, Nextcloud, etc.). + +## Managing Your Account + +### Viewing Enrolled Passkeys + +1. Visit [sso.mynest.love](https://sso.mynest.love). +2. Click **Account** (after signing in). +3. Under **Security Devices**, you'll see all enrolled passkeys. + +### Adding a New Passkey + +1. Go to **Security Devices → Add** on the Keycloak account page. +2. Follow the prompts to register a new device (smartphone, security key, etc.). +3. Give it a recognizable name (e.g., "iPhone 15" or "YubiKey"). + +### Removing a Passkey + +You can remove a passkey from **Security Devices**, but you must have at least one remaining. If you're down to your last passkey, Keycloak will prevent removal and prompt you to add another first. + +## Group-Based Access + +Your access to services is controlled by Keycloak groups. See [Requesting Service Access](../access-requests.md) for details on how to request new groups. + +Common groups include: + +| Group | Services Unlocked | +|-------|-------------------| +| `media-users` | Jellyfin, Sonarr, Radarr, Bazarr | +| `music-users` | DroppedNeedle, slskd | +| `books-users` | Calibre-Web, Shelfmark, Audiobookshelf | +| `storage-users` | Nextcloud | +| `ttrpg-users` | Foundry VTT | + +## Account Recovery + +If you lose access to all enrolled passkeys: + +1. Contact an admin via Matrix (`@nest:starling.mynest.love`). +2. Verify your identity using your registered email address. +3. The admin will reset your account, allowing you to re-enroll passkeys. + +## Related Services + +- [Matrix](../communication-and-security/matrix.md) — Uses Keycloak for SSO login +- [Vaultwarden](../communication-and-security/vaultwarden.md) — Can store passkey credentials securely +- [Forgejo](../productivity-and-creation/forgejo.md) — Uses Keycloak for authentication + +--- + +*TODO: Add screenshot of Keycloak account page showing security devices.* diff --git a/documentation/user-facing/communication-and-security/matrix.md b/documentation/user-facing/communication-and-security/matrix.md new file mode 100644 index 0000000..0293fbb --- /dev/null +++ b/documentation/user-facing/communication-and-security/matrix.md @@ -0,0 +1,56 @@ +# Matrix — Chat, Voice & Video Calls + +**Matrix** is an open standard for decentralized, end-to-end encrypted messaging. The Nest runs [Synapse](https://matrix.org/docs/projects/server/synapse) as the homeserver, with [MAS](https://github.com/element-hq/matrix-authentication-service) for authentication and [LiveKit](https://livekit.io/) for real-time voice/video calls. + +## Access + +| Service | URL | Purpose | +|---------|-----|---------| +| **Synapse (Chat)** | | Send messages, join rooms | +| **MAS (Auth)** | | OAuth2 / passkey authentication | +| **Matrix RTC** | | Voice and video calls | + +## Features + +- End-to-end encrypted messaging +- Group rooms with file sharing +- Real-time voice and video calls via WebRTC +- Federation — connect to other Matrix homeservers +- Bot ecosystem for automation (including The Nest's access bot) + +## Getting Started + +1. Open in your browser or use a Matrix client app. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. You'll be redirected to [sso.mynest.love](https://sso.mynest.love) for passkey authentication. +4. Once authenticated, you're back in Matrix — ready to chat! + +## Recommended Clients + +- **Element Web** (browser): +- **Element X** (mobile): iOS and Android +- **Nheko** (desktop): Windows, macOS, Linux +- **SchildiChat** (alternative web client) + +## Voice & Video Calls + +Matrix RTC uses [LiveKit](https://livekit.io/) for WebRTC signaling and media relay. To join a call: + +1. Open any Matrix room with an active call. +2. Click the **Call** button in the room header. +3. The call connects via — no additional setup needed. + +## Tips + +- **Passkey login:** You'll only need your passkey for initial authentication. Subsequent logins use your client's stored session. +- **Account recovery:** If you lose all passkeys, contact an admin via Matrix (`@nest:starling.mynest.love`) with your registered email for recovery. +- **Federation:** This homeserver is federated. You can message users on other Matrix servers (e.g., `@user:matrix.org`). + +## Related Services + +- [Keycloak](../technical/security-and-identity.md) — Powers passkey authentication via MAS +- [Nest Matrix Bot](https://starling.mynest.love) — The `@access-bot` used for service access requests + +--- + +*TODO: Add screenshot of Element Web with a sample room open.* diff --git a/documentation/user-facing/communication-and-security/vaultwarden.md b/documentation/user-facing/communication-and-security/vaultwarden.md new file mode 100644 index 0000000..6e4bad2 --- /dev/null +++ b/documentation/user-facing/communication-and-security/vaultwarden.md @@ -0,0 +1,51 @@ +# Vaultwarden — Password Manager + +**Vaultwarden** is an open-source, Bitwarden-compatible password manager. It stores passwords, passkeys, secure notes, and other sensitive data in an encrypted vault synced across your devices. + +## Access + +- **Web UI:** +- **Internal (home network):** +- **API:** `https://vault.mynest.love/api` (for third-party clients) + +## Features + +- Store passwords, credit cards, and secure notes +- Sync across all your devices in real time +- Bitwarden-compatible — works with any Bitwarden client +- WebAuthn passkey support for passwordless login to other services +- Two-factor authentication (TOTP or WebAuthn) for the vault itself + +## Getting Started + +1. Open in your browser. +2. Click **Create Account** and follow the setup wizard: + - Choose a **Master Password** (this unlocks your vault — don't forget it!) + - Set up **Two-Factor Authentication** (recommended: WebAuthn passkey) +3. Once set up, you can import passwords from other managers or start adding them manually. + +## Using with The Nest SSO + +Vaultwarden can store the credentials for your other Nest services. For example: + +- Save your Matrix login details in Vaultwarden +- Store Forgejo API tokens securely +- Keep Nextcloud passwords organized + +> [!TIP] +> Since The Nest uses passkey-based authentication, you won't need to save traditional passwords for most services. Use Vaultwarden primarily for services that still require password login or for storing API keys and secrets. + +## Tips + +- **Master Password:** This is the only password you truly need to remember. Store it securely (e.g., written on paper in a safe place) as a backup. +- **Passkey sync:** Enable passkey sync in Vaultwarden settings to use WebAuthn for logging into other Nest services without typing passwords. +- **Browser extension:** Install the Bitwarden browser extension for one-click login to websites that support it. + +## Related Services + +- [Keycloak](../technical/security-and-identity.md) — Issues passkeys used to log into Vaultwarden and other Nest services +- [Matrix](../communication-and-security/matrix.md) — Use Matrix rooms to share secure notes or receive alerts from Vaultwarden (if configured) + +--- + +*TODO: Add screenshot of Vaultwarden vault view with a sample entry.* diff --git a/documentation/user-facing/getting-started.md b/documentation/user-facing/getting-started.md new file mode 100644 index 0000000..1eddc68 --- /dev/null +++ b/documentation/user-facing/getting-started.md @@ -0,0 +1,54 @@ +# Getting Started with The Nest + +Welcome! This guide will walk you through your first steps on **The Nest**, a shared home lab running on three Raspberry Pi 5s in a high-availability Kubernetes cluster. + +## Your Default Account + +When you join The Nest, you are granted access to the following services by default: + +- **Matrix** — Chat and voice/video calls +- **Vaultwarden** — Password manager (Bitwarden-compatible) +- **Forgejo** — Git hosting for code collaboration +- **This Documentation Site** — You're reading it right now + +All other services require an admin to grant you access. See [Requesting Service Access](access-requests.md) for details. + +## Signing In with a Passkey + +The Nest uses **passwordless authentication** powered by [Keycloak](https://keycloak.org/) and WebAuthn passkeys. This means: + +1. You will never log in with a password (after initial setup). +2. You need a **passkey-capable device** — a smartphone, tablet, or computer with a fingerprint reader, face scanner, or security key (e.g., YubiKey). +3. Your **email address is required** for account recovery and initial verification. It is stored securely and not shared with third parties. + +### First-Time Setup + +1. Visit [sso.mynest.love](https://sso.mynest.love) and click **Sign In**. +2. Enter the email address you were provided. +3. Follow the prompts to create your first passkey on your device. +4. Choose a username (this is your Matrix display name and Forgejo handle). + +> [!TIP] +> If you lose access to all your enrolled passkeys, contact an admin via Matrix (`@nest:starling.mynest.love`) for account recovery. You will need to verify your identity using your registered email. + +## Setting Up Vaultwarden (Recommended First Step) + +Before exploring other services, set up [Vaultwarden](vaultwarden.md). It stores your passkeys securely and syncs across devices — making future logins seamless. + +1. Open +2. Click **Master Password** → **I forgot my master password** (first-time flow) +3. Follow the setup wizard to create your vault and enroll a passkey for The Nest SSO. + +## Exploring Services + +Once your account is set up, browse the user-facing guides above to learn about each service. Most will use **"Sign in with The Nest"** as their authentication method — no separate credentials needed. + +## What If Something Goes Wrong? + +- **Can't sign in?** Try a different passkey-capable device or contact an admin via Matrix. +- **Service won't load?** Some services auto-update daily around 03:00 EST. Wait a few minutes and try again. +- **Need help with a specific service?** Ask in the Matrix admin room or open a request via `@access-bot`. + +--- + +*Ready to dive in? Pick a service from the sidebar and start exploring.* diff --git a/documentation/user-facing/media-and-entertainment/audiobookshelf.md b/documentation/user-facing/media-and-entertainment/audiobookshelf.md new file mode 100644 index 0000000..3dcfa1d --- /dev/null +++ b/documentation/user-facing/media-and-entertainment/audiobookshelf.md @@ -0,0 +1,42 @@ +# Audiobookshelf — Audiobooks & Podcasts + +**Audiobookshelf** is a self-hosted audiobook and podcast server. It organizes your collection, tracks listening progress across devices, and supports background playback. + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Organize audiobooks by author, series, or custom tags +- Track progress across devices — pick up where you left off +- Podcast subscription and auto-download +- Background playback and sleep timer (mobile apps) +- Support for MP3, M4B, OPUS, and other common formats + +## Getting Started + +1. Open in your browser or mobile app. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Add your first audiobook folder (if you have local files) or wait for admin-provided content. +4. Start listening! + +## Mobile Apps + +- **Android:** [Audiobookshelf Android](https://github.com/advplyr/audiobookshelf-android) (official) +- **iOS:** Third-party clients like [Foliate](https://github.com/johnfactotum/foliate) or [AntennaPod](https://antennapod.org/) (for podcasts) + +## Tips + +- **Syncing progress:** Make sure you're signed into the same account on all devices for seamless cross-device sync. +- **Podcast subscriptions:** Use the web UI to subscribe to RSS feeds — new episodes download automatically. +- **Bookmarks:** You can set bookmarks on any audiobook chapter via the mobile app or web player. + +## Where Does the Content Come From? + +Audiobooks and podcasts are stored on an NFS share (`robin.home.nest:/yarr/media/audiobooks`). New content is added by the admin. If you have personal audiobook files you'd like to add, ask an admin about mounting your own directory. + +--- + +*TODO: Add screenshot of Audiobookshelf library view.* diff --git a/documentation/user-facing/media-and-entertainment/calibre-web.md b/documentation/user-facing/media-and-entertainment/calibre-web.md new file mode 100644 index 0000000..e6985b4 --- /dev/null +++ b/documentation/user-facing/media-and-entertainment/calibre-web.md @@ -0,0 +1,49 @@ +# Calibre-Web — E-Book Library + +**Calibre-Web** is a web-based e-book manager that provides a clean interface to browse, read, and manage your e-book collection. It connects to a Calibre database for metadata and covers. + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Browse e-books by title, author, series, or tag +- Read books directly in the browser with an integrated viewer +- Download books in your preferred format (EPUB, PDF, MOBI, AZW3) +- Manage metadata: edit titles, authors, covers, and descriptions +- Support for multiple libraries + +## Getting Started + +1. Open in your browser. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Browse the library or use the search bar to find a book. +4. Click **Read Online** to view in-browser, or **Download** to save locally. + +## Supported Formats + +- **EPUB** — Best for most e-readers and apps +- **PDF** — Universal compatibility +- **MOBI / AZW3** — Kindle-compatible formats +- **TXT** — Plain text (no formatting) + +## Tips + +- **Kindle delivery:** If you have a Kindle, use the "Send to Kindle" feature (if enabled by admin) to deliver books directly to your device. +- **Series ordering:** Books in a series are automatically ordered. Use the series view to read them in sequence. +- **Metadata editing:** Some metadata fields can be edited directly in the web UI. Changes sync back to the Calibre database. + +## Where Does the Content Come From? + +E-books are stored on an NFS share (`robin.home.nest:/yarr/media/books/calibre-library`). New books are added by the admin or via the Calibre-Web upload interface (if enabled). The `calibre-ingest` directory is monitored for new files. + +## Related Services + +- [Shelfmark](../productivity-and-creation/shelfmark.md) — Track what you've read and rate books +- [Audiobookshelf](../media-and-entertainment/audiobookshelf.md) — For audiobooks instead of e-books + +--- + +*TODO: Add screenshot of Calibre-Web library with a sample book cover.* diff --git a/documentation/user-facing/media-and-entertainment/droppedneedle.md b/documentation/user-facing/media-and-entertainment/droppedneedle.md new file mode 100644 index 0000000..d5df940 --- /dev/null +++ b/documentation/user-facing/media-and-entertainment/droppedneedle.md @@ -0,0 +1,46 @@ +# DroppedNeedle — Music Discovery & Streaming + +**DroppedNeedle** is a music discovery and streaming service that searches multiple sources (including Usenet and Soulseek) to find and play music. Think of it as a personal Spotify powered by community-shared libraries. + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Search across multiple music sources simultaneously +- Stream found tracks directly in the browser or mobile app +- Automatic FLAC-to-Opus transcoding for storage efficiency +- Library management and playlist creation +- Integration with [slskd](../technical/slskd-soulseek.md) for Soulseek P2P searches + +## Getting Started + +1. Open in your browser or mobile app. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Use the search bar to find a song, album, or artist. +4. Click play — DroppedNeedle will locate and stream the best available source. + +## How It Finds Music + +DroppedNeedle queries multiple backends: + +- **Usenet:** Searches indexed Usenet groups for high-quality releases (requires working indexer configuration). +- **Soulseek:** Queries the [slskd](../technical/slskd-soulseek.md) instance running in The Nest for peer-shared files. +- **Local library:** Plays music already stored on The Nest's NFS share. + +## Tips + +- **Search tips:** Use specific album or artist names for better results. DroppedNeedle prioritizes higher-bitrate sources. +- **Transcoding:** FLAC files are automatically transcoded to Opus (160 kbps) when streamed. Originals remain on disk. +- **Mobile streaming:** Use the DroppedNeedle mobile app (if available) or your device's built-in browser for the best experience. + +## Related Services + +- [slskd](../technical/slskd-soulseek.md) — Soulseek P2P client that feeds DroppedNeedle searches +- [Sonarr/Radarr](../technical/media-automation-pipeline.md#radarr) — Automated movie/TV downloads (not music) + +--- + +*TODO: Add screenshot of DroppedNeedle search results page.* diff --git a/documentation/user-facing/media-and-entertainment/jellyfin.md b/documentation/user-facing/media-and-entertainment/jellyfin.md new file mode 100644 index 0000000..c31eb39 --- /dev/null +++ b/documentation/user-facing/media-and-entertainment/jellyfin.md @@ -0,0 +1,48 @@ +# Jellyfin — Stream Movies & TV Shows + +**Jellyfin** is your personal streaming server, similar to Netflix but running entirely on The Nest. Watch movies and TV shows on any device, anywhere in the house (or remotely via the mynest.love domain). + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Stream video on demand from a shared media library +- Multiple user profiles with individual watch histories and subtitles +- Transcoding support for devices that can't play certain formats natively +- Subtitle support (embedded and external) + +## Getting Started + +1. Open in your browser or Jellyfin app. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Select your profile (or create one if you're new). +4. Browse the library and start watching. + +## Supported Devices + +Jellyfin has official clients for: + +- Web browsers (Chrome, Firefox, Safari, Edge) +- Android / Android TV +- iOS / iPadOS +- Roku +- Apple TV +- Kodi +- [Jellyfin Media Player](https://github.com/jellyfin/jellyfin-media-player) (desktop) + +## Tips + +- **Offline viewing:** Jellyfin doesn't support offline downloads natively. For offline playback, use a dedicated downloader on your device. +- **Quality settings:** You can adjust streaming quality per-device in your profile settings to save bandwidth. +- **Subtitles:** If subtitles don't appear automatically, click the subtitle icon in the player and select your preferred language. + +## Media Library + +The media library is managed by [Sonarr](../technical/media-automation-pipeline.md#sonarr) (TV) and [Radarr](../technical/media-automation-pipeline.md#radarr) (movies). New content appears automatically once downloads complete. + +--- + +*TODO: Add screenshot of Jellyfin home screen with a sample library.* diff --git a/documentation/user-facing/media-request/seerr.md b/documentation/user-facing/media-request/seerr.md new file mode 100644 index 0000000..7c7f652 --- /dev/null +++ b/documentation/user-facing/media-request/seerr.md @@ -0,0 +1,44 @@ +# Seerr — Request Movies & TV Shows + +**Seerr** (formerly *Overseerr*) is a media request and discovery service. Browse what's available to stream, request new titles, and track what your group wants to watch next. + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Browse upcoming movies and TV shows from The Movie Database (TMDB) +- Request titles for automatic download via [Radarr](../technical/media-automation-pipeline.md#radarr) (movies) or [Sonarr](../technical/media-automation-pipeline.md#sonarr) (TV) +- Track request status: pending, processing, available, failed +- User ratings and comments on requested titles + +## Getting Started + +1. Open in your browser. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Search for a movie or TV show you'd like to watch. +4. Click **Request** — the media automation pipeline will handle the rest. + +## How Requests Work + +1. You request a title in Seerr. +2. If the title is available on TMDB, Seerr sends a command to Radarr (movies) or Sonarr (TV). +3. The appropriate service searches indexers, downloads the content, and places it in the media library. +4. Once downloaded, the status updates to **Available** and you can stream it via [Jellyfin](../media-and-entertainment/jellyfin.md). + +## Tips + +- **Search first:** Check if a title is already available before requesting — avoid duplicates. +- **Quality preferences:** You can set default quality preferences (1080p, 4K, etc.) in your Seerr profile settings. +- **TV shows:** Requesting a TV show will download all available seasons. Specify which seasons you want if needed. + +## Related Services + +- [Jellyfin](../media-and-entertainment/jellyfin.md) — Stream requested content once available +- [Sonarr & Radarr](../technical/media-automation-pipeline.md) — Automated downloaders that fulfill requests + +--- + +*TODO: Add screenshot of Seerr home page with a sample movie request.* diff --git a/documentation/user-facing/productivity-and-creation/forgejo.md b/documentation/user-facing/productivity-and-creation/forgejo.md new file mode 100644 index 0000000..fcbfa6d --- /dev/null +++ b/documentation/user-facing/productivity-and-creation/forgejo.md @@ -0,0 +1,38 @@ +# Forgejo — Git Hosting & Code Collaboration + +**Forgejo** is a lightweight, self-hosted git hosting platform (a fork of Gitea). It provides repositories, pull requests, issue tracking, and a package registry — all accessible via your browser or standard git clients. + +## Access + +- **Web UI:** +- **SSH:** `ssh -p 22 git@ssh.weaver.mynest.love` +- **Package Registry:** +- **Internal (home network):** + +## Features + +- Git repository hosting with full history and branching support +- Pull requests with code review workflows +- Issue tracking and project boards +- Built-in CI/CD via Forgejo Actions (GitHub Actions-compatible) +- Container and package registry for sharing binaries and Docker images +- Wiki pages per repository + +## Getting Started + +1. Open in your browser. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Create a new repository or clone an existing one: + + ```bash + git clone ssh://git@ssh.weaver.mynest.love:22/username/repo.git + ``` + +4. Push your first commit and start collaborating. + +## SSH Configuration + +HTTP Git is disabled for security — use SSH only. Add your public key to your Forgejo account under **Settings → SSH Keys**. + +Example `~/.ssh/config` entry: + diff --git a/documentation/user-facing/productivity-and-creation/foundry-vtt.md b/documentation/user-facing/productivity-and-creation/foundry-vtt.md new file mode 100644 index 0000000..2434b80 --- /dev/null +++ b/documentation/user-facing/productivity-and-creation/foundry-vtt.md @@ -0,0 +1,42 @@ +# Foundry VTT — Virtual Tabletop for TTRPGs + +**Foundry Virtual Tabletop (VTT)** is a subscription-free virtual tabletop for playing tabletop role-playing games like Dungeons & Dragons, Pathfinder, and more. It provides maps, tokens, dice rolling, and real-time collaboration. + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Interactive maps with fog of war and dynamic lighting +- Token movement and combat tracking +- Dice rolling with chat integration +- Module and system support for multiple TTRPG rulesets +- Real-time collaboration — multiple players join the same session + +## Getting Started + +1. Open in your browser. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. If this is your first time, you'll be prompted to create a world or join an existing one. +4. Share the session link with your players. + +## How It Works + +Foundry VTT runs as a single-instance server in The Nest. All players connect via WebSocket to the same game world. No separate client software is required — everything runs in the browser. + +## Tips + +- **Worlds:** Each "world" is a separate campaign. Create one per group or setting. +- **Modules:** Install modules for additional rulesets, maps, and tools. Admin-managed module library may be available. +- **Performance:** Foundry VTT is CPU-intensive. If you experience lag, try reducing map detail or closing other browser tabs. +- **Mobile players:** Players can join from phones or tablets via the web UI — no app required. + +## Related Services + +- [Keycloak](../technical/security-and-identity.md) — Handles authentication for Foundry VTT + +--- + +*TODO: Add screenshot of a Foundry VTT combat map with tokens.* diff --git a/documentation/user-facing/productivity-and-creation/shelfmark.md b/documentation/user-facing/productivity-and-creation/shelfmark.md new file mode 100644 index 0000000..69173fb --- /dev/null +++ b/documentation/user-facing/productivity-and-creation/shelfmark.md @@ -0,0 +1,46 @@ +# Shelfmark — Track What You Read & Listen To + +**Shelfmark** is a reading and listening tracker that integrates with [Calibre](https://calibre-ebook.com/) and [Audiobookshelf](../media-and-entertainment/audiobookshelf.md). It provides statistics, ratings, and a clean interface for managing your media consumption. + +## Access + +- **Web UI:** +- **Internal (home network):** + +## Features + +- Track books and audiobooks across Calibre and Audiobookshelf libraries +- Rate and review items after finishing them +- View reading/listening statistics (books per month, genres, etc.) +- Sync progress with downstream services automatically +- OIDC integration — sign in with your Nest account + +## Getting Started + +1. Open in your browser. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Shelfmark will automatically connect to your Calibre and Audiobookshelf libraries (if configured by admin). +4. Start rating and tracking your media! + +## How It Works + +Shelfmark connects to: + +- **Calibre library** — Pulls book metadata, covers, and reading status +- **Audiobookshelf** — Syncs listening progress and ratings +- **Keycloak** — Handles authentication via passkeys + +## Tips + +- **Ratings sync:** Ratings you give in Shelfmark can be pushed back to Calibre/Audiobookshelf (if enabled). +- **Statistics:** Check the stats tab for insights into your reading habits — most-read authors, genres, and yearly summaries. +- **Offline access:** Shelfmark is web-only. For offline tracking, consider a dedicated app like [Readest](https://github.com/readest/readest) or [Foliate](https://github.com/johnfactotum/foliate). + +## Related Services + +- [Calibre-Web](../media-and-entertainment/calibre-web.md) — E-book library (Shelfmark reads from this data) +- [Audiobookshelf](../media-and-entertainment/audiobookshelf.md) — Audiobook server (Shelfmark syncs with this) + +--- + +*TODO: Add screenshot of Shelfmark dashboard showing reading statistics.* diff --git a/documentation/user-facing/storage-and-files/nextcloud.md b/documentation/user-facing/storage-and-files/nextcloud.md new file mode 100644 index 0000000..c12efd8 --- /dev/null +++ b/documentation/user-facing/storage-and-files/nextcloud.md @@ -0,0 +1,61 @@ +# Nextcloud — File Sync, Sharing & Cloud Storage + +**Nextcloud** is a self-hosted file sync and sharing platform. Store files, share them with others, and access them from any device — all under your control. + +## Access + +- **Web UI:** +- **Internal (home network):** +- **DAV / CalDAV / CardDAV:** `https://cloud.mynest.love/remote.php/dav/` + +## Features + +- File storage and synchronization across devices +- Share files and folders via link or with specific users +- Integrated calendar (CalDAV) and contacts (CardDAV) +- Office suite integration for viewing and editing documents +- End-to-end encryption support (optional) + +## Getting Started + +1. Open in your browser. +2. Click **Sign In** and choose **Sign in with The Nest**. +3. Upload files via the web interface or use a sync client. + +## Sync Clients + +Nextcloud provides official clients for: + +- **Desktop:** Windows, macOS, Linux ([Download](https://nextcloud.com/install/#install-clients)) +- **Mobile:** iOS and Android ([App Store](https://apps.nextcloud.com/)) +- **WebDAV:** Configure any DAV-compatible app with the URL above + +### Calendar & Contacts Sync + +Add these to your device's calendar/contacts app: + +| Type | Protocol | URL | +|------|----------|-----| +| Calendar | CalDAV | `https://cloud.mynest.love/remote.php/dav/principals/your-username/` | +| Contacts | CardDAV | `https://cloud.mynest.love/remote.php/dav/principals/your-username/` | + +Sign in with your Nest credentials when prompted. + +## Tips + +- **File versioning:** Nextcloud keeps previous versions of files. Right-click a file → **Versions** to restore an older copy. +- **Sharing links:** Create shareable links with expiration dates and password protection for sensitive files. +- **Offline access:** Use the desktop sync client to keep a local copy of your files for offline work. + +## Backups + +Nextcloud user data is backed up daily at 02:00 EST using Restic to Backblaze B2. Configuration files are snapshotted via Longhorn's recurring backup jobs. + +## Related Services + +- [Keycloak](../technical/security-and-identity.md) — Handles authentication +- [Vaultwarden](../communication-and-security/vaultwarden.md) — Store Nextcloud credentials securely + +--- + +*TODO: Add screenshot of Nextcloud file browser with a sample folder.*