WIP: Technical documenation #3
27 changed files with 1636 additions and 0 deletions
11
Dockerfile
Normal file
11
Dockerfile
Normal file
|
|
@ -0,0 +1,11 @@
|
||||||
|
# Build Stage
|
||||||
|
FROM python:3.11-alpine AS builder
|
||||||
|
RUN pip install mkdocs-material
|
||||||
|
WORKDIR /app
|
||||||
|
COPY . .
|
||||||
|
RUN mkdocs build
|
||||||
|
|
||||||
|
# Serve Stage
|
||||||
|
FROM nginx:alpine
|
||||||
|
COPY --from=builder /app/site /usr/share/nginx/html
|
||||||
|
EXPOSE 80
|
||||||
BIN
docs/assets/logo.png
Normal file
BIN
docs/assets/logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
62
docs/index.md
Normal file
62
docs/index.md
Normal file
|
|
@ -0,0 +1,62 @@
|
||||||
|
# The Nest — Documentation
|
||||||
|
|
||||||
|
Welcome to the documentation for **The Nest**: one bird girl's homelab, shared from me to you!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## For Users
|
||||||
|
|
||||||
|
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
|
||||||
|
</br>
|
||||||
|
</br>
|
||||||
|
- **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
|
||||||
|
- **Media & Entertainment**
|
||||||
|
- [Audiobookshelf](user-facing/media-and-entertainment/audiobookshelf.md) — Audiobooks and podcasts
|
||||||
|
- [Calibre-Web](user-facing/media-and-entertainment/calibre-web.md) — E-book library
|
||||||
|
- [DroppedNeedle](user-facing/media-and-entertainment/droppedneedle.md) — Music discovery and streaming
|
||||||
|
- [Jellyfin](user-facing/media-and-entertainment/jellyfin.md) — Stream movies and TV shows
|
||||||
|
- **Media Request**
|
||||||
|
- [Seerr](user-facing/media-request/seerr.md) — Request movies, TV shows, and anime for Jellyfin
|
||||||
|
- [Shelfmark](user-facing/media-request/shelfmark.md) — Request ebooks and audiobooks for Calibre and Audiobookshelf
|
||||||
|
- **Productivity & Creation**
|
||||||
|
- [Forgejo](user-facing/productivity-and-creation/forgejo.md) — Git hosting and code collaboration
|
||||||
|
- [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, cloud storage, office suite, and more!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Service URLs
|
||||||
|
|
||||||
|
| Service | URL |
|
||||||
|
|---------|-----|
|
||||||
|
| Audiobookshelf | <https://lyrebird.mynest.love> |
|
||||||
|
| Calibre-Web | <https://rookery.mynest.love> |
|
||||||
|
| DroppedNeedle | <https://heron.mynest.love> |
|
||||||
|
| Forgejo | <https://weaver.mynest.love> |
|
||||||
|
| Foundry VTT | <https://foundry.mynest.love> |
|
||||||
|
| Jellyfin | <https://beak.mynest.love> |
|
||||||
|
| Matrix (Synapse) | <https://starling.mynest.love> |
|
||||||
|
| Nextcloud | <https://cloud.mynest.love> |
|
||||||
|
| Seerr | <https://stork.mynest.love> |
|
||||||
|
| Shelfmark | <https://magpie.mynest.love> |
|
||||||
|
| Vaultwarden | <https://vault.mynest.love> |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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.*
|
||||||
6
docs/technical/architecture-overview.md
Normal file
6
docs/technical/architecture-overview.md
Normal file
|
|
@ -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
|
||||||
|
|
||||||
114
docs/technical/backups-and-recovery.md
Normal file
114
docs/technical/backups-and-recovery.md
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
# Backups & Recovery
|
||||||
|
|
||||||
|
The Nest uses a two-tier backup strategy: **Longhorn volume snapshots** for application configuration data (backed up to Backblaze B2 weekly), and **Restic** for Nextcloud user data (backed up daily). Media storage is not backed up.
|
||||||
|
|
||||||
|
## Backup Architecture
|
||||||
|
|
||||||
|
|
||||||
|
## Longhorn Recurring Backups
|
||||||
|
|
||||||
|
Longhorn's built-in recurring job system handles snapshots of all PVCs labeled with `recurring-job.longhorn.io/source: "enabled"` and grouped under `app-config-group`.
|
||||||
|
|
||||||
|
### Schedule
|
||||||
|
|
||||||
|
| Group | Task | Cron | Retain |
|
||||||
|
|-------|------|------|--------|
|
||||||
|
| `app-config-group` | backup | `0 4 * * 0` (Sundays, 04:00 EST) | 4 snapshots |
|
||||||
|
|
||||||
|
### What Gets Backed Up
|
||||||
|
|
||||||
|
Any PVC with the recurring labels is included. This covers:
|
||||||
|
|
||||||
|
- **Application config:** Vault data, Longhorn system volumes
|
||||||
|
- **Service state:** Seerr cache, DroppedNeedle config/cache, Shelfmark config, slskd app data, audiobookshelf metadata/config, sabnzbd config, sonarr/radarr/bazarr configs, nextcloud DB, keykeeper data
|
||||||
|
- **Monitoring:** Prometheus and Grafana PVCs (labeled in HelmChart values)
|
||||||
|
|
||||||
|
### What Does NOT Get Backed Up
|
||||||
|
|
||||||
|
- **Media storage** (`/yarr/media`, `/yarr/downloads`) — NFS shares are not part of Longhorn and have no backups.
|
||||||
|
- **Transcoding scratch space** — DroppedNeedle's transcode PVC is excluded (it regenerates from source FLAC files).
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Longhorn recurring jobs are defined in `longhorn/weekly-backups.yaml`:
|
||||||
|
|
||||||
|
### Backup Destination
|
||||||
|
|
||||||
|
Snapshots are pushed to Backblaze B2 using credentials stored in Vault and synced via the External Secrets Operator (`longhorn/backblaze-secrets.yaml`). The S3-compatible endpoint is configured through `AWS_ENDPOINTS`.
|
||||||
|
|
||||||
|
## Nextcloud User Data Backup
|
||||||
|
|
||||||
|
Nextcloud user data (files, contacts, calendars) is backed up separately using **Restic** to Backblaze B2. This runs as a Kubernetes CronJob in the `nextcloud` namespace.
|
||||||
|
|
||||||
|
### Schedule
|
||||||
|
|
||||||
|
- **Frequency:** Daily at 02:00 EST
|
||||||
|
- **Concurrency policy:** `Forbid` — if a previous run is still active, the new job is skipped.
|
||||||
|
|
||||||
|
### Retention Policy
|
||||||
|
|
||||||
|
| Period | Keep |
|
||||||
|
|--------|------|
|
||||||
|
| Daily | 7 days |
|
||||||
|
| Weekly | 4 weeks |
|
||||||
|
| Monthly | 12 months |
|
||||||
|
|
||||||
|
After retention enforcement, old snapshots are pruned automatically.
|
||||||
|
|
||||||
|
### How It Works
|
||||||
|
|
||||||
|
1. The CronJob spins up a Restic container (`restic/restic:0.16.4`).
|
||||||
|
2. Secrets (B2 credentials, repository URL, password) are injected from Vault via `ExternalSecret`.
|
||||||
|
3. If the B2 repository doesn't exist yet, Restic initializes it on first run.
|
||||||
|
4. The entire Nextcloud user data volume (`/data`) is backed up with verbose output.
|
||||||
|
5. Retention is enforced and old snapshots pruned.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Defined in `services/nextcloud/nextcloud-backups.yaml`:
|
||||||
|
|
||||||
|
### Secrets
|
||||||
|
|
||||||
|
Backblaze credentials are stored in Vault and synced into the cluster via ExternalSecrets (`services/nextcloud/nextcloud-backups.yaml`):
|
||||||
|
|
||||||
|
- `B2_ACCOUNT_ID` — Backblaze application key ID
|
||||||
|
- `B2_ACCOUNT_KEY` — Backblaze application key secret
|
||||||
|
- `RESTIC_REPOSITORY` — B2 bucket path (e.g., `b2:bucket-name:path`)
|
||||||
|
- `RESTIC_PASSWORD` — Encryption password for Restic snapshots
|
||||||
|
|
||||||
|
## Recovery Procedures
|
||||||
|
|
||||||
|
### Recovering a Longhorn Volume Snapshot
|
||||||
|
|
||||||
|
1. Identify the snapshot you want to restore from in the Longhorn UI or via `longhornctl`.
|
||||||
|
2. Create a new volume from the snapshot (or detach and reattach the original).
|
||||||
|
3. Update PVC references if needed.
|
||||||
|
|
||||||
|
### Restoring Nextcloud User Data
|
||||||
|
|
||||||
|
1. Spin up a temporary pod with the Restic image and secrets.
|
||||||
|
2. Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
restic restore latest --target /restore --repo $RESTIC_REPOSITORY
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Copy restored files back to the Nextcloud NFS share (`robin.home.nest:/nextcloud`).
|
||||||
|
|
||||||
|
## Monitoring & Alerts
|
||||||
|
|
||||||
|
Backup health is monitored by the Prometheus stack. Alertmanager sends notifications to Discord for:
|
||||||
|
|
||||||
|
- Failed Longhorn backup jobs
|
||||||
|
- Restic CronJob failures (Nextcloud backups)
|
||||||
|
- Storage capacity warnings on Longhorn volumes
|
||||||
|
|
||||||
|
## Related Documentation
|
||||||
|
|
||||||
|
- [Longhorn Storage](longhorn-storage.md) — Volume management and storage classes
|
||||||
|
- [External Secrets Operator](external-secrets-operator.md) — How Vault secrets are synced into the cluster
|
||||||
|
- [Backblaze B2](https://www.backblaze.com/cloud-storage) — Offsite object storage provider
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*TODO: Add a diagram showing the full backup data flow with timestamps.*
|
||||||
64
docs/technical/networking.md
Normal file
64
docs/technical/networking.md
Normal file
|
|
@ -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 (`<service>.<namespace>.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
|
||||||
57
docs/technical/security-and-identity.md
Normal file
57
docs/technical/security-and-identity.md
Normal file
|
|
@ -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
|
||||||
|
|
||||||
38
docs/user-facing/access-requests.md
Normal file
38
docs/user-facing/access-requests.md
Normal file
|
|
@ -0,0 +1,38 @@
|
||||||
|
# Requesting Additional Service Access
|
||||||
|
|
||||||
|
By default, every new member of **The Nest** receives instant access to our core platforms: **Matrix**, **Vaultwarden**, **Forgejo**, **Foundry VTT**, and this documentation site.
|
||||||
|
|
||||||
|
Looking for access to additional applications? You can easily request access directly through our automated Matrix access bot!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How to Request Access
|
||||||
|
|
||||||
|
Requesting entry to additional services takes just a few simple steps inside Matrix.
|
||||||
|
|
||||||
|
### Step 1: Open a Chat with the Access Bot
|
||||||
|
Start a direct message (DM) in Matrix with:
|
||||||
|
`@access-bot:starling.mynest.love`
|
||||||
|
|
||||||
|
### Step 2: View Available Service Groups
|
||||||
|
In your private chat with the bot, send the following command:
|
||||||
|
`!groups`
|
||||||
|
|
||||||
|
The bot will reply with a list of all available service groups you can request access to.
|
||||||
|
|
||||||
|
### Step 3: Submit Your Request
|
||||||
|
Identify the group name you would like to join, then send:
|
||||||
|
`!request <group_name>`
|
||||||
|
|
||||||
|
*(Be sure to replace `<group_name>` with the exact name provided by the bot in Step 2.)*
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **What Happens Next?**
|
||||||
|
> An administrator will automatically receive a notification with your request and will approve or review it shortly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Responsibilities & Usage
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> Access to any service within The Nest is managed by administrators and can be adjusted or revoked at any time. Please remember to use all shared resources responsibly!
|
||||||
|
|
@ -0,0 +1,66 @@
|
||||||
|
# Managing Your Account & Passkeys
|
||||||
|
|
||||||
|
Your account across **The Nest** is managed by **Keycloak**, our central identity and access platform. Keycloak acts as the digital keyring for all services, ensuring your login experience is seamless, consistent, and passwordless.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What Keycloak Does
|
||||||
|
|
||||||
|
Keycloak works behind the scenes to handle three core functions:
|
||||||
|
|
||||||
|
* **Single Sign-On (SSO):** Log in once to gain access to all connected Nest applications (such as Matrix, Forgejo, or Vaultwarden).
|
||||||
|
* **Passwordless Authentication:** Securely verifies your identity using WebAuthn passkeys instead of traditional passwords.
|
||||||
|
* **Group Access Control:** Grants or restricts access to specific services based on your account's group memberships.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Managing Your Passkeys
|
||||||
|
|
||||||
|
You have full control over your authentication devices! You can view, add, or remove passkeys at any time directly from your account dashboard.
|
||||||
|
|
||||||
|
### Viewing Your Enrolled Passkeys
|
||||||
|
1. Visit [sso.mynest.love](https://sso.mynest.love) and sign in.
|
||||||
|
2. Click on **Account** (or navigate to **Security Devices**).
|
||||||
|
3. Here, you will see a list of all devices and passkeys currently linked to your account.
|
||||||
|
|
||||||
|
### Adding a New Passkey
|
||||||
|
1. From your Keycloak account page, navigate to **Security Devices** and click **Add**.
|
||||||
|
2. Follow your browser or device prompts to register your new passkey (e.g., a smartphone, security key, or browser password manager).
|
||||||
|
3. Give your passkey a recognizable name (such as *"Work Laptop"* or *"Personal iPhone"*) to keep track of your devices easily.
|
||||||
|
|
||||||
|
### Removing a Passkey
|
||||||
|
* To remove an old device, locate it under **Security Devices** and select **Delete**.
|
||||||
|
* **Safety Feature:** Keycloak prevents you from deleting your final remaining passkey to ensure you don't lock yourself out. You must enroll a replacement passkey before removing the last one.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Group-Based Permissions
|
||||||
|
|
||||||
|
Your access to different applications across The Nest is managed through **Keycloak Groups**. In most cases, group names match the service they unlock (for example, belonging to the `foundry-vtt` group gives you access to Foundry VTT).
|
||||||
|
|
||||||
|
To request access to additional services, please see the [Requesting Service Access](../access-requests.md) guide.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Account Recovery
|
||||||
|
|
||||||
|
If you lose access to all of your enrolled devices or passkeys:
|
||||||
|
|
||||||
|
1. Reach out to an administrator on Matrix at `@nest:starling.mynest.love`.
|
||||||
|
2. Verify your identity using the email address linked to your account.
|
||||||
|
3. An administrator will send you a secure recovery link to reset your credentials and register a new passkey.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Services
|
||||||
|
|
||||||
|
Here are a few core platforms that integrate directly with Keycloak:
|
||||||
|
|
||||||
|
* **[Matrix](../communication-and-security/matrix.md):** Unified chat and voice login via SSO.
|
||||||
|
* **[Vaultwarden](../communication-and-security/vaultwarden.md):** Can store and manage passkeys securely across devices.
|
||||||
|
* **[Forgejo](../productivity-and-creation/forgejo.md):** Seamless identity management for code repositories.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> *Screenshots of the Keycloak Security Devices page will be added in a future update!*
|
||||||
79
docs/user-facing/communication-and-security/matrix.md
Normal file
79
docs/user-facing/communication-and-security/matrix.md
Normal file
|
|
@ -0,0 +1,79 @@
|
||||||
|
# Matrix: Chat, Voice & Video Calls
|
||||||
|
|
||||||
|
Welcome to **Matrix**, the primary communication platform for **The Nest**! Matrix powers our group chat rooms, direct messaging, voice channels, and video calling.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Signing In
|
||||||
|
|
||||||
|
Because Matrix is a decentralized messaging network, you will log in by connecting your client app to **The Nest's homeserver**.
|
||||||
|
|
||||||
|
### Step-by-Step Sign In:
|
||||||
|
1. Open your preferred Matrix client or visit [Element Web](https://app.element.io) in your browser.
|
||||||
|
2. Click **Sign In**, and set your homeserver address to:
|
||||||
|
`https://starling.mynest.love`
|
||||||
|
3. Select **"Continue with sso.mynest.love/realms/nest"** when prompted.
|
||||||
|
4. You will be redirected to our standard login screen (`sso.mynest.love`) to authenticate with your passkey.
|
||||||
|
5. Once authenticated, you will be brought right back into Matrix—ready to start chatting!
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **One-Time Authentication:**
|
||||||
|
> You only need to use your passkey for initial login on a new device. Your client app will stay securely signed in until you manually log out.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Recommended Clients
|
||||||
|
|
||||||
|
One of the best features of Matrix is that you can choose your own application client! However, because features like video calling and screen sharing require WebRTC support, we recommend using one of the official **Element** applications:
|
||||||
|
|
||||||
|
* **Element Desktop** *(Windows, macOS, Linux)*: The recommended option for desktop users, featuring full screen-sharing and multi-party video call support.
|
||||||
|
* **Element X** *(iOS & Android)*: A modern, high-performance mobile client for chatting on the go.
|
||||||
|
* **Element Web** *(Browser)*: Accessible immediately from any modern Web browser at [app.element.io](https://app.element.io).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Coming from Discord? (Quick Comparison)
|
||||||
|
|
||||||
|
If you are accustomed to Discord, Matrix has a slightly different vocabulary, but the core concepts map over naturally:
|
||||||
|
|
||||||
|
| Discord Concept | Matrix Equivalent | How It Works in The Nest |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Discord** | **Homeserver** | The host server managing your account (ours is `starling.mynest.love`). The Matrix ecosystem is just a bunch of people hosting their own Discords. Neat! |
|
||||||
|
| **Server** | **Space** | A folder structure used to organize multiple rooms together. Anyone can create a private or public Space. |
|
||||||
|
| **Text / Voice Channel** | **Room** | Where messaging happens! In Matrix, every room (including 1-on-1 direct messages) supports text, voice, and video. |
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **Federation (Connecting Beyond The Nest):**
|
||||||
|
> Matrix is *federated*. This means you can use your Nest account to join public rooms or send direct messages to users on other Matrix homeservers across the internet (such as `@username:matrix.org`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Voice & Video Calls
|
||||||
|
|
||||||
|
Matrix handles voice and video calls seamlessly using real-time WebRTC media streaming.
|
||||||
|
|
||||||
|
### How to Join a Call:
|
||||||
|
1. Open any Matrix room with an active discussion.
|
||||||
|
2. Click the **Call** button (phone or camera icon) in the top header.
|
||||||
|
3. The call connects automatically via `matrix-rtc.mynest.love`—no extra configuration needed!
|
||||||
|
|
||||||
|
*Screen sharing is supported when using desktop clients like **Element Desktop**.*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. System Service Endpoints
|
||||||
|
|
||||||
|
For reference or advanced client setup, here are the service endpoints powering Matrix on The Nest:
|
||||||
|
|
||||||
|
| Service Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Homeserver (Synapse)** | `https://starling.mynest.love` | Handles chat messages and room routing |
|
||||||
|
| **Authentication Service (MAS)** | `https://mas.mynest.love` | Manages OAuth2 authentication flows |
|
||||||
|
| **Matrix RTC (LiveKit)** | `https://matrix-rtc.mynest.love` | Powers high-quality voice and video calls |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Troubleshooting & Related Services
|
||||||
|
|
||||||
|
* **Requesting Access to New Services:** Send a direct message to `@access-bot:starling.mynest.love` inside Matrix to request permissions.
|
||||||
|
* **Central Authentication:** Keycloak manages single sign-on access across Matrix and connected services.
|
||||||
85
docs/user-facing/communication-and-security/vaultwarden.md
Normal file
85
docs/user-facing/communication-and-security/vaultwarden.md
Normal file
|
|
@ -0,0 +1,85 @@
|
||||||
|
# Vaultwarden: Secure Password Management
|
||||||
|
|
||||||
|
**Vaultwarden** is the official password manager hosted on **The Nest**. Powered by a self-hosted implementation of Bitwarden, Vaultwarden provides an encrypted vault to safely store your passwords, passkeys, credit cards, secure notes, and two-factor authentication (2FA) codes across all your devices.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Why Use Vaultwarden over Other Password Managers?
|
||||||
|
|
||||||
|
With so many password management options available, here is why we encourage using Vaultwarden on The Nest:
|
||||||
|
|
||||||
|
* **Complete Privacy & Data Ownership:** Your passwords are encrypted and hosted locally on The Nest rather than on commercial cloud servers owned by Big Tech companies.
|
||||||
|
* **True Multi-Device Syncing:** Browser-based password managers (like Chrome or Safari) lock your credentials into a specific browser or operating system. Vaultwarden syncs seamlessly across Windows, macOS, Linux, iOS, Android, and every major browser via official Bitwarden apps.
|
||||||
|
* **Integrated Passkey & 2FA Support:** Store WebAuthn passkeys and built-in authenticator (TOTP) codes in one single, secure location—no need for separate authenticator apps!
|
||||||
|
* **Full Premium Feature Set:** Nest users receive full access to Bitwarden-compatible premium features (such as 2FA generation, secure attachment storage, and emergency access) at zero extra cost.
|
||||||
|
* **Automatic Backups vs. Local Files:** Local password files (like KeePass or un-synced text stores) risk permanent data loss if a device is damaged or lost. Vaultwarden keeps your vault synced in real time while benefit from automated Nest backups.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Getting Started & Account Setup
|
||||||
|
|
||||||
|
1. **Check Your Inbox:** When your Nest account is created, you will receive an invitation email containing a registration link.
|
||||||
|
2. **Set Your Master Password:** Click the invite link to create your account and set a strong **Master Password**.
|
||||||
|
3. **Save Your Master Password:** This password encrypts your entire vault. Make sure to write it down or store it in a safe place!
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> **Important:** Because Vaultwarden uses zero-knowledge encryption, administrators **cannot** view or reset your Master Password if you forget it. Always keep a physical backup of your Master Password in a secure location!
|
||||||
|
|
||||||
|
*If your invite link has expired before setup, simply reach out to an administrator on Matrix to request a new invitation.*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. How to Migrate Your Passwords into Vaultwarden
|
||||||
|
|
||||||
|
Moving your existing credentials from Chrome, Firefox, Apple Passwords, 1Password, or LastPass into Vaultwarden is quick and easy!
|
||||||
|
|
||||||
|
### Step 1: Export Credentials from Your Current Manager
|
||||||
|
Export your saved passwords as an unencrypted **CSV** or **JSON** file from your current browser or password manager settings.
|
||||||
|
|
||||||
|
### Step 2: Import Your File into Vaultwarden
|
||||||
|
1. Log in to the Vaultwarden Web Console at [vault.mynest.love](https://vault.mynest.love).
|
||||||
|
2. In the top navigation bar, click **Tools**, then select **Import Data**.
|
||||||
|
3. Choose the format corresponding to your old manager (e.g., *"Chrome (csv)"* or *"1Password (csv)"*).
|
||||||
|
4. Select your exported file and click **Import Data**.
|
||||||
|
|
||||||
|
### Step 3: Clean Up
|
||||||
|
> [!CAUTION]
|
||||||
|
> **Security Reminder:** Once your import is complete, immediately delete the exported `.csv` or `.json` file from your device and empty your Trash/Recycle Bin. Export files contain your passwords in plain text!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Connecting Your Apps & Devices
|
||||||
|
|
||||||
|
Vaultwarden uses standard **Bitwarden** client applications. When signing in to any Bitwarden extension or app for the first time, click the **Gear Icon (Settings)** on the sign-in screen and set your **Server URL** to:
|
||||||
|
|
||||||
|
`https://vault.mynest.love`
|
||||||
|
|
||||||
|
### Recommended Downloads:
|
||||||
|
* **Browser Extension:** Install the **Bitwarden** browser extension (Chrome, Firefox, Edge, Safari) for one-click password auto-fill on websites.
|
||||||
|
* **Mobile Apps:** Download **Bitwarden** from the iOS App Store or Google Play Store to enable system-wide password and passkey auto-fill on smartphones.
|
||||||
|
* **Desktop App:** Available for macOS, Windows, and Linux for quick access to your vault off-browser.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Integrating with The Nest
|
||||||
|
|
||||||
|
While The Nest relies primarily on **passwordless passkeys** managed via Keycloak SSO for logging into services like Matrix or Forgejo, Vaultwarden is an essential companion:
|
||||||
|
|
||||||
|
* **Passkey Vaulting:** Vaultwarden can securely store and sync passkeys used for both Nest services and external websites.
|
||||||
|
* **Credential Organization:** Safely store API keys, personal notes, credit cards, or recovery codes for all your digital accounts.
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **Passkey Auto-Fill:**
|
||||||
|
> If you use the Bitwarden browser extension or mobile app, enable passkey support in the extension settings to sign into Nest services with a single click!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Service Endpoints & Related Services
|
||||||
|
|
||||||
|
| Component | URL | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Vaultwarden Web UI** | [vault.mynest.love](https://vault.mynest.love) | Web vault, import tools, and account settings |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Keycloak Identity](../technical/security-and-identity.md):** Powers central passkey logins across The Nest.
|
||||||
|
* **[Matrix Chat](../communication-and-security/matrix.md):** Get in touch with an administrator if you need help with your vault.
|
||||||
82
docs/user-facing/getting-started.md
Normal file
82
docs/user-facing/getting-started.md
Normal file
|
|
@ -0,0 +1,82 @@
|
||||||
|
# Welcome to The Nest: Getting Started Guide
|
||||||
|
|
||||||
|
Welcome to **The Nest**! This guide serves as your starting point for creating your account, navigating available services, and getting support whenever you need it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Requesting Access
|
||||||
|
|
||||||
|
Ready to join the flock? Head over to [fledgling.mynest.love](https://fledgling.mynest.love) to submit your account request.
|
||||||
|
|
||||||
|
To complete your request, you will need:
|
||||||
|
* **A Username:** Choose carefully! Usernames cannot be easily changed once created.
|
||||||
|
* **A Working Email Address:** Email aliases are completely fine. This address will be used for your initial setup, account recovery, and optional service notifications.
|
||||||
|
|
||||||
|
Once submitted, an administrator will review your request and approve your access.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Signing In with a Passkey
|
||||||
|
|
||||||
|
The Nest uses **passwordless authentication** (powered by Keycloak and WebAuthn). Instead of remembering complex passwords, you'll log in securely using a **passkey**.
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **What is a Passkey?**
|
||||||
|
> A passkey lets you sign in using your physical device or password manager instead of typing a password. You will use the exact same passkey for all services across The Nest.
|
||||||
|
|
||||||
|
### What You Need
|
||||||
|
To sign in, you will need a passkey-compatible device or tool, such as:
|
||||||
|
* A smartphone or tablet
|
||||||
|
* A computer equipped with a fingerprint reader or face scanner
|
||||||
|
* A hardware security key (such as a YubiKey)
|
||||||
|
* A passkey-capable password manager like **Vaultwarden**
|
||||||
|
|
||||||
|
### First-Time Account Setup
|
||||||
|
|
||||||
|
Once your account is approved by an administrator, you will receive two emails:
|
||||||
|
1. **An invitation to Vaultwarden** (an optional password manager service).
|
||||||
|
2. **Setup instructions** directing you to this guide.
|
||||||
|
|
||||||
|
If you would like to use Vaultwarden, accept the invite; if not, feel free to ignore it.
|
||||||
|
|
||||||
|
**To complete your initial sign-in:**
|
||||||
|
1. Navigate to [sso.mynest.love](https://sso.mynest.love) and click **Sign In**.
|
||||||
|
2. Enter the account username and temporary password provided in your setup details.
|
||||||
|
*(Note: This is the **only** time you will use a traditional password.)*
|
||||||
|
3. Follow the on-screen prompts to register a passkey on your device.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Your Default Account Services
|
||||||
|
|
||||||
|
Upon joining The Nest, you automatically gain access to several core platforms:
|
||||||
|
|
||||||
|
| Service | Description |
|
||||||
|
| :--- | :--- |
|
||||||
|
| **Matrix** | Group chat, direct messaging, and voice/video calling |
|
||||||
|
| **Vaultwarden** | Bitwarden-compatible password manager for securing credentials |
|
||||||
|
| **Forgejo** | Code hosting and collaborative project workspace |
|
||||||
|
| **Documentation Site** | The user guide platform you are currently reading |
|
||||||
|
| **Foundry VTT** | Virtual tabletop platform for tabletop RPG games |
|
||||||
|
|
||||||
|
*Additional services require separate administrator authorization. Please review the [Requesting Service Access](access-requests.md) guide for more information.*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Exploring & Signing Into Services
|
||||||
|
|
||||||
|
As you explore the user guides for each platform, signing in is straightforward. Most services use a single button labeled **"Sign in with The Nest"**.
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **Terminology Tip:**
|
||||||
|
> Depending on the app, you might see phrases like *"Sign in with OIDC"*, *"Sign in with Keycloak"*, or *"Sign in with SSO"*. These all mean the exact same thing: sign in using your standard Nest passkey!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Troubleshooting & Support
|
||||||
|
|
||||||
|
If you run into any issues along the way, here is how to resolve them:
|
||||||
|
|
||||||
|
* **Unable to Sign In?** Try using a different passkey-supported device, or reach out to an administrator on Matrix.
|
||||||
|
* **Service Unavailable or Unresponsive?** Systems undergo automated daily updates around **03:00 EST**. Please wait a few minutes and refresh your browser.
|
||||||
|
* **Need General Assistance?** Head over to the **Admin** space in Matrix and drop your question in the **"Ask an Admin"** room.
|
||||||
62
docs/user-facing/media-and-entertainment/audiobookshelf.md
Normal file
62
docs/user-facing/media-and-entertainment/audiobookshelf.md
Normal file
|
|
@ -0,0 +1,62 @@
|
||||||
|
# Audiobookshelf: Audiobooks & Podcasts
|
||||||
|
|
||||||
|
**Audiobookshelf** is the dedicated audio library server for **The Nest**. It organizes your personal audiobook and podcast collections, tracks listening progress seamlessly across all your devices, and supports background playback.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Signing In
|
||||||
|
|
||||||
|
Accessing Audiobookshelf is quick and simple using your central Nest account:
|
||||||
|
|
||||||
|
1. Open **[lyrebird.mynest.love](https://lyrebird.mynest.love)** in your Web browser or mobile app.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Authenticate using your standard Nest passkey.
|
||||||
|
4. Pick a book or podcast episode and start listening!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Recommended Mobile Apps
|
||||||
|
|
||||||
|
To take your audiobooks and podcasts on the go, connect your smartphone using one of the recommended client apps:
|
||||||
|
|
||||||
|
### Android
|
||||||
|
* **Audiobookshelf (Official):** Available on the [Google Play Store](https://play.google.com/store/apps/details?id=com.audiobookshelf.app) or [GitHub Releases](https://github.com/advplyr/audiobookshelf-android). Offers full feature parity including offline downloads and progress sync.
|
||||||
|
|
||||||
|
### iOS (iPhone & iPad)
|
||||||
|
* **Dedicated iOS Clients:** Native iOS apps like **Plappa**, **ShelfPlayer**, **AudioBooth**, or **Absorb** connect directly to your server.
|
||||||
|
* **Server Connection:** When configuring any mobile client, set your server URL to:
|
||||||
|
`https://lyrebird.mynest.love`
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **Connecting Mobile Apps:**
|
||||||
|
> When logging in via mobile apps, select the option to sign in via **OpenID / Single Sign-On** to authenticate using your standard Nest passkey.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Features & Listening Tips
|
||||||
|
|
||||||
|
* **Cross-Device Syncing:** Your listening progress, current chapter, and playback speed automatically sync between the Web interface and mobile apps. Just ensure you are signed into the same Nest account on each device!
|
||||||
|
* **Bookmarks & Notes:** Set custom bookmarks with optional notes on any chapter to easily jump back to favorite moments.
|
||||||
|
* **Sleep Timers & Playback Speed:** Fine-tune your listening experience with customizable playback speeds and chapter-based sleep timers.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Where Does Content Come From?
|
||||||
|
|
||||||
|
Audiobookshelf draws its library directly from central storage on The Nest.
|
||||||
|
|
||||||
|
Want to add a new audiobook to the library?
|
||||||
|
* You can request new titles through **[Shelfmark](../media-request/shelfmark.md)**!
|
||||||
|
* Once requested, Shelfmark automatically processes the audiobook and populates it directly into your Audiobookshelf library.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Description |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Audiobookshelf Web UI** | [lyrebird.mynest.love](https://lyrebird.mynest.love) | Web player, library management, and account settings |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Shelfmark](../media-request/shelfmark.md):** Request new audiobooks to automatically populate your library.
|
||||||
|
* **[Calibre-Web](../media-and-entertainment/calibre-web.md):** Read e-books and digital publications on your e-reader or mobile device.
|
||||||
94
docs/user-facing/media-and-entertainment/calibre-web.md
Normal file
94
docs/user-facing/media-and-entertainment/calibre-web.md
Normal file
|
|
@ -0,0 +1,94 @@
|
||||||
|
# Calibre-Web: E-Book Library & Sync
|
||||||
|
|
||||||
|
**Calibre-Web** is the digital book library for **The Nest**. It provides a clean interface to browse, read, and manage your e-book collection, complete with in-browser reading, e-reader sync support, and automatic reading tracking.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Reading Online
|
||||||
|
|
||||||
|
1. Visit **[rookery.mynest.love](https://rookery.mynest.love)** in your web browser.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Log in using your standard Nest passkey.
|
||||||
|
4. Search or browse through the library by title, author, series, or tag.
|
||||||
|
5. Click **Read Online** to read directly in your browser, or **Download** to save a copy in your preferred format (EPUB, PDF, MOBI, etc.).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Connecting E-Readers (OPDS & KoSync)
|
||||||
|
|
||||||
|
Calibre-Web supports **OPDS** (Open Publication Distribution System) for browsing and downloading books directly on e-readers, as well as **KoSync** for syncing your reading progress and bookmarks across multiple devices.
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> **Application Key Required for E-Readers**
|
||||||
|
>
|
||||||
|
> Standard passkeys and Single Sign-On do **not** work directly inside third-party e-reader apps. To connect an e-reader app, you must generate a dedicated **Application Key**:
|
||||||
|
>
|
||||||
|
> 1. Log in to [rookery.mynest.love](https://rookery.mynest.love) in your web browser.
|
||||||
|
> 2. Open your **Account Settings**.
|
||||||
|
> 3. Under **Application Keys**, enter a label (e.g., *"KOReader Kobo"* or *"Readest iPhone"*) and click **Generate**.
|
||||||
|
> 4. **Copy the key immediately!** It will only be displayed once. (We recommend saving it in **Vaultwarden**).
|
||||||
|
|
||||||
|
### E-Reader Endpoints & Login Credentials
|
||||||
|
When logging in from an e-reader app, use the following credentials:
|
||||||
|
* **Username:** Your Nest username
|
||||||
|
* **Password:** Your generated **Application Key**
|
||||||
|
|
||||||
|
| Protocol | Service URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **OPDS** | `https://rookery.mynest.love/opds` | Browse and download books directly on your e-reader |
|
||||||
|
| **KoSync** | `https://rookery.mynest.love/sync` | Sync reading progress and bookmarks across devices |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Recommended E-Reader Clients
|
||||||
|
|
||||||
|
You can connect any app that supports OPDS or KoSync. Here are our top recommended e-reader applications:
|
||||||
|
|
||||||
|
* **[KOReader](https://koreader.rocks/):** *(Available for Android, Kindle, Kobo, Windows, Linux)* — The premier open-source reading application featuring native OPDS browsing and built-in KoSync support.
|
||||||
|
* **[Readest](https://readest.app/):** *(Available for iOS)* — A sleek, modern e-reader app for iPhone and iPad with built-in OPDS support.
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **Have a Kindle?**
|
||||||
|
> If you'd like to install KOReader on a Kindle, check out [Kindle Mod Shelf](https://kindlemodshelf.me/) for jailbreaking guides! Alternatively, you can use the web interface's *"Send to Kindle"* feature to deliver EPUB or MOBI files directly to your Amazon account.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Where Does Content Come From?
|
||||||
|
|
||||||
|
To keep metadata, covers, and series details clean and consistent, direct file uploads inside Calibre-Web are disabled.
|
||||||
|
|
||||||
|
* **Requesting New Books:** Request any e-book title via **[Shelfmark](../media-request/shelfmark.md)**! Shelfmark automatically fetches high-quality metadata and imports the book directly into Calibre-Web.
|
||||||
|
* **Contributing Existing Libraries:** Have a large collection of e-books you'd like to share with The Nest? Reach out to an administrator on Matrix to arrange a batch import!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Hardcover Reading Tracker Integration
|
||||||
|
|
||||||
|
Love tracking your reading stats and sharing book reviews? Calibre-Web integrates natively with **[Hardcover](https://hardcover.app)**:
|
||||||
|
|
||||||
|
1. Create a free account at [hardcover.app](https://hardcover.app).
|
||||||
|
2. Generate an **API Token** in your Hardcover account settings.
|
||||||
|
3. Paste the token into your Calibre-Web account settings on [rookery.mynest.love](https://rookery.mynest.love).
|
||||||
|
|
||||||
|
Once linked, books you read in Calibre-Web will automatically sync with your Hardcover profile!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Supported File Formats
|
||||||
|
|
||||||
|
* **EPUB:** The recommended standard for e-readers, mobile apps, and web reading. *(Most non-EPUB formats are automatically converted to EPUB upon import).*
|
||||||
|
* **PDF:** Ideal for fixed-layout documents, comics, and technical manuals.
|
||||||
|
* **MOBI / AZW3:** Amazon Kindle legacy formats.
|
||||||
|
* **TXT:** Plain text files.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Calibre-Web UI** | [rookery.mynest.love](https://rookery.mynest.love) | Web interface, online reading, and account settings |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Shelfmark](../media-request/shelfmark.md):** Request new e-books to automatically populate the library.
|
||||||
|
* **[Audiobookshelf](../media-and-entertainment/audiobookshelf.md):** Listen to audiobooks and podcasts.
|
||||||
82
docs/user-facing/media-and-entertainment/droppedneedle.md
Normal file
82
docs/user-facing/media-and-entertainment/droppedneedle.md
Normal file
|
|
@ -0,0 +1,82 @@
|
||||||
|
# DroppedNeedle: Music Discovery & Streaming
|
||||||
|
|
||||||
|
**DroppedNeedle** is the primary music discovery and streaming service for **The Nest**. It searches across multiple sources—including local storage, Usenet, and Soulseek peer-to-peer shares—to help you find, play, and build your music collection. Think of it as your personal, self-hosted streaming service powered by community-shared media!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Signing In
|
||||||
|
|
||||||
|
1. Open **[heron.mynest.love](https://heron.mynest.love)** in your Web browser or mobile app.
|
||||||
|
2. Switch to the **SSO** tab on the sign-in screen.
|
||||||
|
3. Click **Continue with SSO**.
|
||||||
|
4. Authenticate using your central Nest passkey.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Streaming Music & Mobile Apps
|
||||||
|
|
||||||
|
DroppedNeedle acts as a **Subsonic-compatible music server**. This means you can stream music directly in your Web browser or connect any Subsonic-supported mobile application!
|
||||||
|
|
||||||
|
* **Web Player:** Stream lossless audio directly from your Web browser with no setup required.
|
||||||
|
* **Mobile Apps:** Choose from any [Subsonic-compatible client](https://www.subsonic.org/pages/apps.jsp) (such as Symfonium, Feishin, or Ample) to stream on iOS or Android.
|
||||||
|
* **Automated Transcoding:** High-fidelity FLAC files are automatically transcoded to high-efficiency **160 kbps Opus** when streaming to save mobile data and storage space.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. How Music Discovery & Requests Work
|
||||||
|
|
||||||
|
Unlike movie or TV requests, DroppedNeedle lets you search and request music directly—no administrator approval needed!
|
||||||
|
|
||||||
|
1. Use the main search bar to search for a song, album, or artist.
|
||||||
|
2. DroppedNeedle queries multiple sources simultaneously:
|
||||||
|
* **Local Library:** Music already stored in The Nest's shared collection.
|
||||||
|
* **Usenet Indexers:** High-speed indexers for full releases and albums.
|
||||||
|
* **Soulseek (slskd):** Peer-to-peer network search for rare tracks and obscure releases.
|
||||||
|
* **YouTube:** Stream music directly from YouTube if it's available, or preview songs before adding them to your library.
|
||||||
|
3. Click **Play** to stream immediately, or **Download** to pull the track into the library.
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **Help Keep the Library Clean!**
|
||||||
|
> Occasionally, DroppedNeedle needs help matching a rare file. Visit the **Downloads** tab to review pending downloads, select correct releases, or verify track tagging. Helping review downloads ensures the library stays organized for everyone!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Recommendations & Scrobbling (ListenBrainz & Last.fm)
|
||||||
|
|
||||||
|
Want weekly mixes and personalized artist recommendations? DroppedNeedle supports scrobbling (listening history sync) with **ListenBrainz** and **Last.fm**:
|
||||||
|
|
||||||
|
1. Create a free account on [ListenBrainz](https://listenbrainz.org) or [Last.fm](https://www.last.fm).
|
||||||
|
2. Navigate to your **Profile Settings** inside DroppedNeedle.
|
||||||
|
3. Log into your ListenBrainz and/or Last.fm account and enable **Scrobbling**.
|
||||||
|
|
||||||
|
Once connected, DroppedNeedle will automatically generate custom weekly mixes and artist recommendations based on your listening habits!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Following Artists & Local Concert Tracking
|
||||||
|
|
||||||
|
Keep up with your favorite musicians directly inside DroppedNeedle:
|
||||||
|
|
||||||
|
* **New Release Alerts:** Follow an artist to receive notifications when new singles or albums are released.
|
||||||
|
* **Local Concert & Event Tracking:** Navigate to the **Following** tab and select **Coming Up**. Enter your location, and DroppedNeedle will aggregate upcoming concerts and live events near you via sources like Ticketmaster!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Syncing Spotify Playlists
|
||||||
|
|
||||||
|
You can sync your existing Spotify playlists directly over to DroppedNeedle! However, please note:
|
||||||
|
|
||||||
|
* **Developer API Limit:** Spotify limits developer apps to a maximum of **5 connected accounts** simultaneously.
|
||||||
|
* **Setup Request:** Because of API constraints, Spotify playlist sync must be enabled manually by an admin. If you would like to connect your Spotify account, drop a request in the Matrix **"Ask an Admin"** room!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **DroppedNeedle Web UI** | [heron.mynest.love](https://heron.mynest.love) | Web streaming, music search, and library management |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[slskd (Soulseek)](../technical/slskd-soulseek.md):** The peer-to-peer backend supporting music searches.
|
||||||
|
* **[Matrix Chat](../communication-and-security/matrix.md):** Reach out to an admin to request Spotify playlist integration.
|
||||||
62
docs/user-facing/media-and-entertainment/jellyfin.md
Normal file
62
docs/user-facing/media-and-entertainment/jellyfin.md
Normal file
|
|
@ -0,0 +1,62 @@
|
||||||
|
# Jellyfin: Stream Movies & TV Shows
|
||||||
|
|
||||||
|
**Jellyfin** is the primary video streaming service for **The Nest**. Similar to commercial streaming platforms like Netflix or Hulu, Jellyfin allows you to stream movies, TV series, and documentaries on demand across all your devices.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Web Access & Initial Setup
|
||||||
|
|
||||||
|
1. Open **[beak.mynest.love](https://beak.mynest.love)** in your Web browser.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Log in using your standard Nest passkey.
|
||||||
|
4. Browse the library and start watching!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Connecting Smart TVs & Mobile Apps (Quick Connect)
|
||||||
|
|
||||||
|
Jellyfin offers official app support across almost every major platform:
|
||||||
|
|
||||||
|
* **Living Room / TV Apps:** Android TV, Apple TV, Roku, Fire TV, Kodi
|
||||||
|
* **Mobile / Desktop Apps:** iOS (iPhone/iPad), Android, Windows, macOS, Linux
|
||||||
|
* **Web Browsers:** Chrome, Firefox, Safari, Edge
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **Signing In on TV Apps (Quick Connect)**
|
||||||
|
> Smart TV apps cannot process passkey logins directly. To sign into a TV or streaming device, use **Quick Connect**:
|
||||||
|
>
|
||||||
|
> 1. Open the Jellyfin app on your TV or streaming device and select **Quick Connect**. A short code will appear on your TV screen.
|
||||||
|
> 2. On your phone or computer browser, go to [beak.mynest.love](https://beak.mynest.love) and sign in using your passkey.
|
||||||
|
> 3. Click your **Profile Icon** in the top-right corner and select **Quick Connect**.
|
||||||
|
> 4. Enter the code shown on your TV screen and click **Authorize**.
|
||||||
|
> 5. Your TV will instantly log into your account!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Requesting New Movies & TV Shows
|
||||||
|
|
||||||
|
Looking for a specific movie or TV show that isn't in the library yet?
|
||||||
|
|
||||||
|
* **Submit Requests:** You can request new titles through **[Seerr](../media-requests/seerr.md)**!
|
||||||
|
* **Automated Sync:** Once requested, media moves through our automated ingest pipeline and automatically populates in Jellyfin.
|
||||||
|
* **Library Scans:** Jellyfin scans for new media regularly. If a newly approved request doesn't appear immediately, please wait up to 24 hours for automated library indexing. If content is still missing after 24 hours, reach out to an administrator on Matrix.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Playback & Viewing Tips
|
||||||
|
|
||||||
|
* **Subtitle Options & Syncing:** Subtitles can be enabled directly inside the video player. If subtitle timing feels slightly out of sync, many clients (including the Web browser player) allow you to adjust the **Subtitle Offset** in the player settings to align dialogue perfectly.
|
||||||
|
* **Bandwidth & Quality Controls:** If you are on a limited mobile data connection, you can adjust your streaming bitrate and resolution per-device in your profile playback settings.
|
||||||
|
* **Offline Playback:** Jellyfin does not support native offline downloads. Content must be streamed while connected to the internet.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Jellyfin Web UI** | [beak.mynest.love](https://beak.mynest.love) | Web streaming, user profiles, and Quick Connect authorization |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Seerr](../media-requests/seerr.md):** Request new movies and TV series to populate Jellyfin.
|
||||||
|
* **[Matrix Chat](../communication-and-security/matrix.md):** Contact an admin if media fails to sync after 24 hours.
|
||||||
65
docs/user-facing/media-request/seerr.md
Normal file
65
docs/user-facing/media-request/seerr.md
Normal file
|
|
@ -0,0 +1,65 @@
|
||||||
|
# Seerr: Request Movies & TV Shows
|
||||||
|
|
||||||
|
**Seerr** (formerly *Overseerr*) is the central media discovery and request portal for **The Nest**. It allows you to browse trending movies, discover upcoming TV series, submit requests for new titles, and track what our community is watching next.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Signing In
|
||||||
|
|
||||||
|
1. Open **[stork.mynest.love](https://stork.mynest.love)** in your Web browser.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Log in using your standard Nest passkey.
|
||||||
|
4. Search for a movie or TV show using the search bar, or explore trending lists powered by The Movie Database (TMDB).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. How to Request Media
|
||||||
|
|
||||||
|
Requesting new content takes just a couple of clicks!
|
||||||
|
|
||||||
|
### Request Steps:
|
||||||
|
1. Search for the movie, TV series, or anime you want to watch.
|
||||||
|
2. Check the status badge on the title:
|
||||||
|
* If it says **Available**, it is already in our library and ready to stream on [Jellyfin](../media-and-entertainment/jellyfin.md)!
|
||||||
|
* If it is not in the library, click **Request**.
|
||||||
|
3. For TV series, choose whether to request all seasons or select specific seasons.
|
||||||
|
4. Select your preferred Quality Profile and click **Submit Request**.
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> **Important Rule for Anime Requests!**
|
||||||
|
> When requesting an Anime series or movie, you **must** select the **Anime** profile from the profile dropdown instead of the default profile. Because anime formatting and episode numbering differ from Western TV releases, using the default profile will cause the automated request to fail.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. How Requests Are Processed & Timelines
|
||||||
|
|
||||||
|
Once your request is submitted, The Nest's media pipeline processes it automatically:
|
||||||
|
|
||||||
|
1. **Request Submission:** Seerr validates your request and sends it to our automated download system (Radarr for movies, Sonarr for TV shows).
|
||||||
|
2. **Automated Retrieval:** The backend locates high-quality releases, downloads the content, and places it into the shared media storage.
|
||||||
|
3. **Status Update:** Once complete, the request status in Seerr updates to **Available**.
|
||||||
|
|
||||||
|
### Fulfillment Timelines:
|
||||||
|
* **Standard Requests:** Popular movies or recent TV episodes are usually downloaded within a couple of hours.
|
||||||
|
* **Jellyfin Library Indexing:** It can take up to **24 hours** for newly downloaded files to automatically index and appear in Jellyfin.
|
||||||
|
* **Stuck or Missing Requests?** If a title remains in *Pending* or *Processing* status for longer than 24 hours, the media may be rare or unavailable. Reach out to an administrator on Matrix to check its status!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Helpful Tips
|
||||||
|
|
||||||
|
* **Search Before Requesting:** Always search the library first to avoid submitting duplicate requests for media that is already available or currently processing.
|
||||||
|
* **Default Quality Settings:** You can configure default quality preferences (such as preferred resolution) inside your Seerr profile settings.
|
||||||
|
* **Community Features:** Explore the **Requests** tab to see what other members are looking forward to watching, or leave ratings and comments on titles.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Seerr Web UI** | [stork.mynest.love](https://stork.mynest.love) | Media discovery, title searching, and request management |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Jellyfin](../media-and-entertainment/jellyfin.md):** Stream requested movies and TV series once available.
|
||||||
|
* **[Media Automation Pipeline](../technical/media-automation-pipeline.md):** Technical documentation on the Sonarr and Radarr backend downloaders.
|
||||||
57
docs/user-facing/media-request/shelfmark.md
Normal file
57
docs/user-facing/media-request/shelfmark.md
Normal file
|
|
@ -0,0 +1,57 @@
|
||||||
|
# Shelfmark: Request E-Books & Audiobooks
|
||||||
|
|
||||||
|
**Shelfmark** is the media request portal for digital books and spoken media across **The Nest**. Whether you are looking for an e-book to read on your e-reader or an audiobook to listen to on the go, Shelfmark lets you browse catalog titles and submit requests for automated library delivery.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Signing In
|
||||||
|
|
||||||
|
1. Open **[magpie.mynest.love](https://magpie.mynest.love)** in your Web browser.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Log in using your standard Nest passkey.
|
||||||
|
4. Search or browse the catalog for a title you would like to read or listen to.
|
||||||
|
5. Click **Request**—Shelfmark will process the request and add the title to your library!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. How Requests Work & Delivery Targets
|
||||||
|
|
||||||
|
Once you submit a request, Shelfmark automatically processes the title and routes it to the appropriate platform:
|
||||||
|
|
||||||
|
* **E-Books:** Ingested directly into your **[Calibre-Web](../media-and-entertainment/calibre-web.md)** library for web reading or e-reader syncing.
|
||||||
|
* **Audiobooks:** Ingested directly into your **[Audiobookshelf](../media-and-entertainment/audiobookshelf.md)** library for mobile listening and progress tracking.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Search Modes & Requesting Tips
|
||||||
|
|
||||||
|
To get the best results when searching for new media, keep these helpful tips in mind:
|
||||||
|
|
||||||
|
* **Check Existing Libraries First:** Shelfmark does not automatically index items already stored on The Nest. Please search [Calibre-Web](../media-and-entertainment/calibre-web.md) or [Audiobookshelf](../media-and-entertainment/audiobookshelf.md) first to ensure the title isn't already available before submitting a new request.
|
||||||
|
* **Select the Right Search Mode:** Shelfmark features three distinct search modes:
|
||||||
|
* **E-Book Mode:** Filters results specifically for readable digital books.
|
||||||
|
* **Audiobook Mode:** Filters results specifically for spoken audio recordings.
|
||||||
|
* **Universal Mode:** Searches for both e-books and audiobooks simultaneously.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Supported Formats
|
||||||
|
|
||||||
|
Shelfmark automatically sources the highest-quality releases available for your requested media:
|
||||||
|
|
||||||
|
* **E-Book Formats:** Sourced primarily in **EPUB**, **PDF**, or **MOBI**.
|
||||||
|
* **Audiobook Formats:** Sourced primarily in **M4B** or high-efficiency **OPUS**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Shelfmark Web UI** | [magpie.mynest.love](https://magpie.mynest.love) | Catalog browsing and e-book / audiobook request portal |
|
||||||
|
|
||||||
|
### Related Nest Services:
|
||||||
|
* **[Calibre-Web](../media-and-entertainment/calibre-web.md):** Read requested e-books in your browser or sync to an e-reader.
|
||||||
|
* **[Audiobookshelf](../media-and-entertainment/audiobookshelf.md):** Stream and listen to requested audiobooks across your devices.
|
||||||
|
* **[Seerr](seerr.md):** Request movies and TV shows for video streaming.
|
||||||
|
* **[DroppedNeedle](../media-and-entertainment/droppedneedle.md):** Discover, stream, and request music releases.
|
||||||
117
docs/user-facing/productivity-and-creation/forgejo.md
Normal file
117
docs/user-facing/productivity-and-creation/forgejo.md
Normal file
|
|
@ -0,0 +1,117 @@
|
||||||
|
# Forgejo: Git Hosting & Code Collaboration
|
||||||
|
|
||||||
|
**Forgejo** is the central self-hosted Git platform for **The Nest**. A lightweight fork of Gitea, Forgejo provides version control, code review workflows, issue tracking, and container/package registries—all fully integrated into our single sign-on identity system.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Web Access & Initial Setup
|
||||||
|
|
||||||
|
1. Open **[weaver.mynest.love](https://weaver.mynest.love)** in your Web browser.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Log in using your standard Nest passkey.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Setting Up SSH Keys (Required for Git Push/Pull)
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> **HTTP Git Access is Disabled**
|
||||||
|
> For security reasons, HTTP/HTTPS Git cloning and pushing are completely disabled on The Nest. All command-line Git interactions must use **SSH**.
|
||||||
|
|
||||||
|
To interact with repositories from your terminal or command line, you must add your SSH public key to your Forgejo account.
|
||||||
|
|
||||||
|
### Step 1: Generate an SSH Key Pair
|
||||||
|
If you don't already have an SSH key, open your terminal (macOS/Linux) or Git Bash / PowerShell (Windows) and run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh-keygen -t ed25519 -C "your_email@example.com"
|
||||||
|
```
|
||||||
|
Press `Enter` to accept the default file location. You can optionally enter a passphrase for extra security.
|
||||||
|
|
||||||
|
### Step 2: Copy Your Public Key
|
||||||
|
Display and copy your **public** key (never share or copy your private key!):
|
||||||
|
|
||||||
|
* **macOS:** `pbcopy < ~/.ssh/id_ed25519.pub`
|
||||||
|
* **Linux:** `xclip -selection clipboard < ~/.ssh/id_ed25519.pub` (or `cat ~/.ssh/id_ed25519.pub`)
|
||||||
|
* **Windows (PowerShell):** `Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard`
|
||||||
|
|
||||||
|
### Step 3: Add Your Public Key to Forgejo
|
||||||
|
1. Sign into **[weaver.mynest.love](https://weaver.mynest.love)**.
|
||||||
|
2. Click your profile avatar in the top-right corner and select **Settings**.
|
||||||
|
3. Select **SSH / GPG Keys** from the left sidebar.
|
||||||
|
4. Click **Add Key**.
|
||||||
|
5. Give your key a recognizable name (e.g., `MacBook Pro` or `Desktop Workstation`), paste your copied public key into the **Content** box, and click **Add Key**.
|
||||||
|
|
||||||
|
### Step 4: Test Your SSH Connection
|
||||||
|
In your terminal, test your authentication against The Nest's SSH Git server:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh -T -p 22 git@ssh.weaver.mynest.love
|
||||||
|
```
|
||||||
|
|
||||||
|
If configured correctly, Forgejo will output a welcome message confirming successful authentication!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. How to Contribute & Collaborate
|
||||||
|
|
||||||
|
Whether you are writing code, tweaking configuration files, or reporting bugs, everyone can contribute to projects hosted on The Nest.
|
||||||
|
|
||||||
|
### Option A: Opening Issues (Bug Reports & Feature Requests)
|
||||||
|
If you find something broken, want to request a feature, or need to ask a question:
|
||||||
|
|
||||||
|
1. Navigate to the project's repository on **[weaver.mynest.love](https://weaver.mynest.love)**.
|
||||||
|
2. Click the **Issues** tab at the top of the repository.
|
||||||
|
3. Click the green **New Issue** button.
|
||||||
|
4. Fill in a descriptive **Title**.
|
||||||
|
5. In the **Description** box, include:
|
||||||
|
* **Summary:** What is the issue or feature request?
|
||||||
|
* **Steps to Reproduce:** (For bugs) Step-by-step instructions to recreate the problem.
|
||||||
|
* **Expected vs. Actual Behavior:** What you expected to happen vs. what actually happened.
|
||||||
|
6. Click **Create Issue**. You will automatically receive updates when project maintainers comment or update the issue status.
|
||||||
|
|
||||||
|
### Option B: Contributing Code via Pull Requests
|
||||||
|
1. **Clone the repository using SSH:**
|
||||||
|
```bash
|
||||||
|
git clone git@ssh.weaver.mynest.love:organization/repository-name.git
|
||||||
|
```
|
||||||
|
2. **Create a local working branch:**
|
||||||
|
```bash
|
||||||
|
git checkout -b feature/my-changes
|
||||||
|
```
|
||||||
|
3. **Commit and push your changes:**
|
||||||
|
```bash
|
||||||
|
git commit -m "Describe your changes clearly"
|
||||||
|
git push origin feature/my-changes
|
||||||
|
```
|
||||||
|
4. **Open a Pull Request:** Navigate to the repository on Forgejo, click **New Pull Request**, select your branch, and submit it for review.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Package Registry & CI/CD Pipelines
|
||||||
|
|
||||||
|
### Container & Package Registry
|
||||||
|
Forgejo hosts a built-in package registry for sharing container images and dependencies:
|
||||||
|
|
||||||
|
* **Docker / OCI Registry:**
|
||||||
|
```bash
|
||||||
|
docker pull weaver.mynest.love/nest/your-image:tag
|
||||||
|
```
|
||||||
|
* **Language Package Managers (npm / Python / Go):**
|
||||||
|
Generate a personal access token under **Settings → Applications → Generate Token**, then configure your local package manager to authenticate with `weaver.mynest.love`.
|
||||||
|
|
||||||
|
### Automated Workflows (Forgejo Actions)
|
||||||
|
Repositories can automate builds, tests, and deployments using Forgejo Actions (compatible with GitHub Actions syntax). Place your workflow definition files inside `.forgejo/workflows/` in your repository root.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | Endpoint / URL | Access Method | Purpose |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **Web UI** | [weaver.mynest.love](https://weaver.mynest.love) | Browser (Passkey) | Repository management, issue tracking, and PRs |
|
||||||
|
| **Git SSH Server** | `ssh.weaver.mynest.love` (Port `22`) | SSH Key | Command-line Git cloning, pulling, and pushing |
|
||||||
|
| **Package Registry** | [weaver.mynest.love/packages](https://weaver.mynest.love/packages) | API / Token | Container images and package management |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Semaphore](https://semaphore.k3s.home.nest):** Ansible automation UI for infrastructure deployment and execution.
|
||||||
56
docs/user-facing/productivity-and-creation/foundry-vtt.md
Normal file
56
docs/user-facing/productivity-and-creation/foundry-vtt.md
Normal file
|
|
@ -0,0 +1,56 @@
|
||||||
|
# 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, Call of Cthulhu, and more. Hosted directly on **The Nest**, Foundry provides interactive maps, dynamic lighting, integrated character sheets, soundscapes, and real-time multiplayer collaboration.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Web Access & Initial Setup
|
||||||
|
|
||||||
|
1. Open **[foundry.mynest.love](https://foundry.mynest.love)** in your Web browser.
|
||||||
|
2. Click **Sign In** and log in using your standard Nest passkey.
|
||||||
|
3. Select your assigned **User Profile** from the campaign dropdown menu and enter your player passcode (if set by your GM).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Core Concepts: Worlds, Systems, and Modules
|
||||||
|
|
||||||
|
To get the most out of Foundry VTT, it helps to understand its three primary layers:
|
||||||
|
|
||||||
|
* **Game Systems:** The underlying rules engine (e.g., *D&D 5e*, *Pathfinder 2e*, *Alien RPG*). Systems define character sheet statistics, automated combat rolls, and rules calculations.
|
||||||
|
* **Worlds:** The individual campaign instance containing scenes (maps), actors (player characters and NPCs), roll tables, and journal entries.
|
||||||
|
* **Modules:** Community-created add-ons that enhance functionality (such as 3D dice animations, automation macros, UI tweaks, or map effects).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Running Your Own Game on The Nest
|
||||||
|
|
||||||
|
Want to run a campaign or one-shot for your gaming group on The Nest?
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> **Single-Instance Server & Admin Access**
|
||||||
|
> Foundry VTT runs as a single service on The Nest, which means **only one World (campaign) can be actively hosted at any given time**.
|
||||||
|
>
|
||||||
|
> * **Admin Password:** Switching active campaign Worlds or installing new Game Systems and Modules requires the server's admin password.
|
||||||
|
> * **Requesting GM Access:** Reach out to an administrator on Matrix to get the administrative password and receive a quick setup overview.
|
||||||
|
> * **Session Scheduling:** Be sure to schedule game times with other GMs on Matrix to avoid schedule overlaps or accidental world switching during live sessions!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Tips for Players & GMs
|
||||||
|
|
||||||
|
* **Hardware Acceleration:** Foundry uses WebGL to render dynamic lighting, fog of war, and canvas effects. Ensure **Hardware Acceleration** is turned **ON** in your browser settings (`chrome://settings` or Firefox settings) for smooth performance.
|
||||||
|
* **Recommended Devices:** While mobile devices can technically access the web interface, a desktop, laptop, or tablet with a dedicated mouse/trackpad is strongly recommended for managing map vision and token navigation.
|
||||||
|
* **Performance Tuning:** If you experience lagging or high fan noise, lower the **Maximum Frame Rate** or disable soft shadows under **Settings → Configure Settings → Core Settings**.
|
||||||
|
* **Audio & Video Setup:** Foundry includes native browser WebRTC for audio and video calls. Be sure to grant camera and microphone permissions when prompted by your browser, or hop in a room in Matrix!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Service Summary & Related Links
|
||||||
|
|
||||||
|
| Component | Endpoint / URL | Access Method | Purpose |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **Foundry Web UI** | [foundry.mynest.love](https://foundry.mynest.love) | Web Browser | Connect to active tabletop campaign worlds |
|
||||||
|
| **Official Documentation** | [foundryvtt.com/kb](https://foundryvtt.com/kb/) | External Link | Official Foundry VTT Knowledge Base and user guides |
|
||||||
|
|
||||||
|
### Related Nest Documentation:
|
||||||
|
* **[Matrix Chat](../communication-and-security/matrix.md):** Coordinate game night schedules with other GMs or request admin credentials.
|
||||||
88
docs/user-facing/storage-and-files/nextcloud.md
Normal file
88
docs/user-facing/storage-and-files/nextcloud.md
Normal file
|
|
@ -0,0 +1,88 @@
|
||||||
|
# Nextcloud: Cloud Storage, Office Suite & Productivity Hub
|
||||||
|
|
||||||
|
**Nextcloud** (Nextcloud Hub) is the primary cloud storage, document collaboration, and groupware platform for **The Nest**. Far more than a simple file dump, Nextcloud combines cross-device file synchronization, real-time collaborative document editing, shared calendars, contacts, and productivity tools into a unified, privacy-focused portal.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Web Access & Initial Setup
|
||||||
|
|
||||||
|
1. Open **[cloud.mynest.love](https://cloud.mynest.love)** in your Web browser.
|
||||||
|
2. Click **Sign In** and select **"Sign in with The Nest"**.
|
||||||
|
3. Log in using your standard Nest passkey.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Core Features & Capabilities
|
||||||
|
|
||||||
|
* **File Storage & Synchronization:** Store files securely with continuous background sync across desktop and mobile devices.
|
||||||
|
* **File Versioning & Recovery:** Nextcloud automatically tracks file history. Right-click any file and select **Versions** to inspect or restore prior edits.
|
||||||
|
* **Secure File Sharing:** Share files and folders internally with Nest members or publicly via shareable links. Public shares can be secured with passwords, expiration dates, and download restrictions.
|
||||||
|
* **Project Management (Deck):** Organize team tasks and personal projects using built-in Kanban boards.
|
||||||
|
* **Activity Stream:** Track recent edits, file uploads, and comments across your shared folders in real time.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Nextcloud Office Suite (Collaborative Editing)
|
||||||
|
|
||||||
|
Nextcloud includes a full-featured, browser-based office suite (powered by Nextcloud Office) for working with documents, spreadsheets, and presentations:
|
||||||
|
|
||||||
|
* **Real-Time Co-Authoring:** Multiple users can open and edit the same document simultaneously with live cursor tracking, in-document chatting, and revision history.
|
||||||
|
* **Native Microsoft & OpenDocument Support:** Seamlessly view, edit, and export formats including Word (`.docx`, `.doc`), Excel (`.xlsx`, `.xls`), PowerPoint (`.pptx`), and OpenDocument (`.odt`, `.ods`, `.odp`).
|
||||||
|
* **In-Browser Document Creation:** Create new text documents, spreadsheets, or presentation decks directly from the Nextcloud **Files** interface without needing local office software installed.
|
||||||
|
* **Comments & Annotations:** Add comments, tag team members using `@mentions`, and track suggested changes directly within documents.
|
||||||
|
* **PDF Viewing & Annotation:** View, search, and annotate PDF files directly inside your browser window.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Calendar, Contacts & Tasks Integration (CalDAV / CardDAV)
|
||||||
|
|
||||||
|
Nextcloud provides built-in CalDAV and CardDAV endpoints for syncing your calendars, address books, and tasks across mobile and desktop applications.
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **Authentication Note for Native Apps (App Passwords)**
|
||||||
|
> Native calendar and contact apps on iOS, macOS, Android, or Thunderbird cannot use passkeys directly.
|
||||||
|
>
|
||||||
|
> * Before configuring your app, go to **Settings → Security → Devices & Sessions** in Nextcloud.
|
||||||
|
> * Generate a new **App Password** (e.g., named "iPhone Calendar").
|
||||||
|
> * Copy the generated password and use it as your account password during device setup.
|
||||||
|
|
||||||
|
### Integration Endpoints & Manual Setup
|
||||||
|
|
||||||
|
| Type | Protocol | Base / Auto-Discovery URL | Direct Server Path |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **Primary DAV Endpoint** | WebDAV / DAV | `https://cloud.mynest.love/remote.php/dav/` | Auto-discovers calendars & contacts |
|
||||||
|
| **Calendar (CalDAV)** | CalDAV | `https://cloud.mynest.love/remote.php/dav/` | `/remote.php/dav/principals/users/<your-username>/` |
|
||||||
|
| **Contacts (CardDAV)** | CardDAV | `https://cloud.mynest.love/remote.php/dav/` | `/remote.php/dav/principals/users/<your-username>/` |
|
||||||
|
|
||||||
|
### Setting Up Sync on Your Devices:
|
||||||
|
* **iOS / macOS:** Go to **System Settings → Internet Accounts → Add Account → Add Other Account → CalDAV Account (or CardDAV)**. Select **Advanced** and set the Server Address to `cloud.mynest.love` and the Server Path to `/remote.php/dav/principals/users/<your-username>/`. Alternatively, copy the exact subscription link by opening the Nextcloud **Calendar app → ⚙ Calendar settings → Copy iOS/macOS CalDAV address**.
|
||||||
|
* **Android:** Install **[DAVx⁵](https://www.davx5.com/)** from Google Play or F-Droid, choose **Login with URL and user name**, and enter `https://cloud.mynest.love/remote.php/dav/` alongside your username and App Password.
|
||||||
|
* **Thunderbird / Desktop:** Thunderbird autodiscovers all calendars and address books simply by adding a new Calendar and logging in with your Nextcloud URL and credentials.
|
||||||
|
|
||||||
|
*For detailed device-specific guides, consult the [Official Nextcloud Groupware Sync Documentation](https://docs.nextcloud.com/server/latest/user_manual/en/groupware/index.html).*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Sync Clients & Mobile Apps
|
||||||
|
|
||||||
|
* **Desktop Sync Client:** Sync local folders with Nextcloud on Windows, macOS, and Linux ([Download Clients](https://nextcloud.com/install/#install-clients)). Supports **Virtual Files** (files are visible locally but downloaded on demand to save disk space).
|
||||||
|
* **Mobile Apps (iOS & Android):** Browse files on the go and enable **Auto-Upload** in the app settings to automatically back up phone photos and videos directly to your Nextcloud cloud storage.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Service Summary & Infrastructure Notes
|
||||||
|
|
||||||
|
| Component | URL / Endpoint | Purpose |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Web UI** | [cloud.mynest.love](https://cloud.mynest.love) | Primary cloud portal, office suite, and web manager |
|
||||||
|
| **DAV / CalDAV / CardDAV** | `https://cloud.mynest.love/remote.php/dav/` | Synchronization endpoint for files, calendars, and contacts |
|
||||||
|
|
||||||
|
### Backups & Data Protection:
|
||||||
|
* **User Data:** Backed up daily at **02:00 EST** using Restic to offsite Backblaze B2 storage.
|
||||||
|
* **Configuration & Database:** Application state and cluster configurations are snapshotted via Longhorn recurring backup tasks.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Nest Documentation:
|
||||||
|
* **[Forgejo](../technical/forgejo.md):** Git code hosting and package management.
|
||||||
|
* **[Matrix Chat](../communication-and-security/matrix.md):** Instant messaging and administrative support.
|
||||||
47
mkdocs.yaml
Normal file
47
mkdocs.yaml
Normal file
|
|
@ -0,0 +1,47 @@
|
||||||
|
site_name: The Nest Documentation
|
||||||
|
theme:
|
||||||
|
name: material
|
||||||
|
logo: assets/logo.png
|
||||||
|
favicon: assets/logo.png
|
||||||
|
features:
|
||||||
|
- navigation.expand
|
||||||
|
- navigation.instant
|
||||||
|
- navigation.sections
|
||||||
|
palette:
|
||||||
|
# Palette toggle for light mode
|
||||||
|
- scheme: default
|
||||||
|
primary: indigo
|
||||||
|
accent: indigo
|
||||||
|
toggle:
|
||||||
|
icon: material/brightness-7
|
||||||
|
name: Switch to dark mode
|
||||||
|
|
||||||
|
# Palette toggle for dark mode
|
||||||
|
- scheme: slate
|
||||||
|
primary: indigo
|
||||||
|
accent: indigo
|
||||||
|
toggle:
|
||||||
|
icon: material/brightness-4
|
||||||
|
name: Switch to light mode
|
||||||
|
nav:
|
||||||
|
- Home: index.md
|
||||||
|
- User Facing:
|
||||||
|
- Getting Started: user-facing/getting-started.md
|
||||||
|
- Access Requests: user-facing/access-requests.md
|
||||||
|
- Communication and Security:
|
||||||
|
- Keycloak Account: user-facing/communication-and-security/keycloak-account.md
|
||||||
|
- Matrix: user-facing/communication-and-security/matrix.md
|
||||||
|
- Vaultwarden: user-facing/communication-and-security/vaultwarden.md
|
||||||
|
- Media and Entertainment:
|
||||||
|
- Audiobookshelf: user-facing/media-and-entertainment/audiobookshelf.md
|
||||||
|
- Calibre: user-facing/media-and-entertainment/calibre-web.md
|
||||||
|
- DroppedNeedle: user-facing/media-and-entertainment/droppedneedle.md
|
||||||
|
- Jellyfin: user-facing/media-and-entertainment/jellyfin.md
|
||||||
|
- Media Requests:
|
||||||
|
- Seerr: user-facing/media-request/seerr.md
|
||||||
|
- Shelfmark: user-facing/media-request/shelfmark.md
|
||||||
|
- Productivity and Creation:
|
||||||
|
- Forgejo (Git): user-facing/productivity-and-creation/forgejo.md
|
||||||
|
- Foundry VTT: user-facing/productivity-and-creation/foundry-vtt.md
|
||||||
|
- Storage and Files:
|
||||||
|
- Nextcloud: user-facing/storage-and-file/nextcloud.md
|
||||||
1
requirements.txt
Normal file
1
requirements.txt
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
mkdocs-material==9.5.3
|
||||||
6
technical/architecture-overview.md
Normal file
6
technical/architecture-overview.md
Normal file
|
|
@ -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
|
||||||
|
|
||||||
114
technical/backups-and-recovery.md
Normal file
114
technical/backups-and-recovery.md
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
# Backups & Recovery
|
||||||
|
|
||||||
|
The Nest uses a two-tier backup strategy: **Longhorn volume snapshots** for application configuration data (backed up to Backblaze B2 weekly), and **Restic** for Nextcloud user data (backed up daily). Media storage is not backed up.
|
||||||
|
|
||||||
|
## Backup Architecture
|
||||||
|
|
||||||
|
|
||||||
|
## Longhorn Recurring Backups
|
||||||
|
|
||||||
|
Longhorn's built-in recurring job system handles snapshots of all PVCs labeled with `recurring-job.longhorn.io/source: "enabled"` and grouped under `app-config-group`.
|
||||||
|
|
||||||
|
### Schedule
|
||||||
|
|
||||||
|
| Group | Task | Cron | Retain |
|
||||||
|
|-------|------|------|--------|
|
||||||
|
| `app-config-group` | backup | `0 4 * * 0` (Sundays, 04:00 EST) | 4 snapshots |
|
||||||
|
|
||||||
|
### What Gets Backed Up
|
||||||
|
|
||||||
|
Any PVC with the recurring labels is included. This covers:
|
||||||
|
|
||||||
|
- **Application config:** Vault data, Longhorn system volumes
|
||||||
|
- **Service state:** Seerr cache, DroppedNeedle config/cache, Shelfmark config, slskd app data, audiobookshelf metadata/config, sabnzbd config, sonarr/radarr/bazarr configs, nextcloud DB, keykeeper data
|
||||||
|
- **Monitoring:** Prometheus and Grafana PVCs (labeled in HelmChart values)
|
||||||
|
|
||||||
|
### What Does NOT Get Backed Up
|
||||||
|
|
||||||
|
- **Media storage** (`/yarr/media`, `/yarr/downloads`) — NFS shares are not part of Longhorn and have no backups.
|
||||||
|
- **Transcoding scratch space** — DroppedNeedle's transcode PVC is excluded (it regenerates from source FLAC files).
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Longhorn recurring jobs are defined in `longhorn/weekly-backups.yaml`:
|
||||||
|
|
||||||
|
### Backup Destination
|
||||||
|
|
||||||
|
Snapshots are pushed to Backblaze B2 using credentials stored in Vault and synced via the External Secrets Operator (`longhorn/backblaze-secrets.yaml`). The S3-compatible endpoint is configured through `AWS_ENDPOINTS`.
|
||||||
|
|
||||||
|
## Nextcloud User Data Backup
|
||||||
|
|
||||||
|
Nextcloud user data (files, contacts, calendars) is backed up separately using **Restic** to Backblaze B2. This runs as a Kubernetes CronJob in the `nextcloud` namespace.
|
||||||
|
|
||||||
|
### Schedule
|
||||||
|
|
||||||
|
- **Frequency:** Daily at 02:00 EST
|
||||||
|
- **Concurrency policy:** `Forbid` — if a previous run is still active, the new job is skipped.
|
||||||
|
|
||||||
|
### Retention Policy
|
||||||
|
|
||||||
|
| Period | Keep |
|
||||||
|
|--------|------|
|
||||||
|
| Daily | 7 days |
|
||||||
|
| Weekly | 4 weeks |
|
||||||
|
| Monthly | 12 months |
|
||||||
|
|
||||||
|
After retention enforcement, old snapshots are pruned automatically.
|
||||||
|
|
||||||
|
### How It Works
|
||||||
|
|
||||||
|
1. The CronJob spins up a Restic container (`restic/restic:0.16.4`).
|
||||||
|
2. Secrets (B2 credentials, repository URL, password) are injected from Vault via `ExternalSecret`.
|
||||||
|
3. If the B2 repository doesn't exist yet, Restic initializes it on first run.
|
||||||
|
4. The entire Nextcloud user data volume (`/data`) is backed up with verbose output.
|
||||||
|
5. Retention is enforced and old snapshots pruned.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Defined in `services/nextcloud/nextcloud-backups.yaml`:
|
||||||
|
|
||||||
|
### Secrets
|
||||||
|
|
||||||
|
Backblaze credentials are stored in Vault and synced into the cluster via ExternalSecrets (`services/nextcloud/nextcloud-backups.yaml`):
|
||||||
|
|
||||||
|
- `B2_ACCOUNT_ID` — Backblaze application key ID
|
||||||
|
- `B2_ACCOUNT_KEY` — Backblaze application key secret
|
||||||
|
- `RESTIC_REPOSITORY` — B2 bucket path (e.g., `b2:bucket-name:path`)
|
||||||
|
- `RESTIC_PASSWORD` — Encryption password for Restic snapshots
|
||||||
|
|
||||||
|
## Recovery Procedures
|
||||||
|
|
||||||
|
### Recovering a Longhorn Volume Snapshot
|
||||||
|
|
||||||
|
1. Identify the snapshot you want to restore from in the Longhorn UI or via `longhornctl`.
|
||||||
|
2. Create a new volume from the snapshot (or detach and reattach the original).
|
||||||
|
3. Update PVC references if needed.
|
||||||
|
|
||||||
|
### Restoring Nextcloud User Data
|
||||||
|
|
||||||
|
1. Spin up a temporary pod with the Restic image and secrets.
|
||||||
|
2. Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
restic restore latest --target /restore --repo $RESTIC_REPOSITORY
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Copy restored files back to the Nextcloud NFS share (`robin.home.nest:/nextcloud`).
|
||||||
|
|
||||||
|
## Monitoring & Alerts
|
||||||
|
|
||||||
|
Backup health is monitored by the Prometheus stack. Alertmanager sends notifications to Discord for:
|
||||||
|
|
||||||
|
- Failed Longhorn backup jobs
|
||||||
|
- Restic CronJob failures (Nextcloud backups)
|
||||||
|
- Storage capacity warnings on Longhorn volumes
|
||||||
|
|
||||||
|
## Related Documentation
|
||||||
|
|
||||||
|
- [Longhorn Storage](longhorn-storage.md) — Volume management and storage classes
|
||||||
|
- [External Secrets Operator](external-secrets-operator.md) — How Vault secrets are synced into the cluster
|
||||||
|
- [Backblaze B2](https://www.backblaze.com/cloud-storage) — Offsite object storage provider
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*TODO: Add a diagram showing the full backup data flow with timestamps.*
|
||||||
64
technical/networking.md
Normal file
64
technical/networking.md
Normal file
|
|
@ -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 (`<service>.<namespace>.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
|
||||||
57
technical/security-and-identity.md
Normal file
57
technical/security-and-identity.md
Normal file
|
|
@ -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
|
||||||
|
|
||||||
Loading…
Add table
Reference in a new issue