k3s/documentation/context.txt

This git repo contains all of the config for a k3s cluster called "The Nest". The Nest is my Homelab setup running off of 3 mirrored rpi5s with attached longhorn and etcd storage, enabling a highly resiliant HA setup. I also have a custom domain, "mynest.love", which routes to an HAProxy instance running on my pfSense router that serves as ingress into the Nest.

For the last few months I have been preparring The Nest so that I can share it with my friends and family. One of the things I would like to do is provide documentation on what's available in the Nest, how to access it, and how to use it. To that end, I would like you to write documentation for each service you come across in this repo. The documentation should broadly be split into two categories: user-facing and technical. User-facing documentation should contain explinations of services that are accessible to end-users over the mynest.love domain. User-facing documentation is intended for non-technical audience and should be focused on general information and how-tos. An example of a service user-facing documentation should be written foris "DroppedNeedle" (services/droppedneedle). Technical documentation should include information on backend services, architecture, data, networking, and security. Technical documentation is intended for a technical audience. An example of a service technical documentation should be written for is metallb. Being a user-facing service does not preclude a service from having technical documentation in addition to its user-facing documentation if that topic is complex enough to warrent a technical writeup.

Documentation should be written to the "documentation" folder.
I would like the documentation to be organized by function/topic. For example, services dealing with media should be grouped together and perhaps further broken down by media type (music, TV/Movies, books, etc.).
The documentation should be easy to navigate and search, with links where appropriate. Those links may be to other documents or resources on the internet (ex. GitHub pages, Wikipedia, or homepages).
The documentation should not be overly verbose. Do a second pass on all documents written optomizing for conciseness and clarity.
The documentation should be written in in standard Markdown format so that it can be easily edited and converted into a webpage.
The documentation should be consistent in format, layout, and tone across services, though that format and tone may differ between user-facing and technical documentation.
The documentation should be consistent in the facts. Cross-reference your own work to avoid hallucinations.

As you are writing the documentation consider the following additional context where appropriate:
- Backups of longhorn storage are conducted daily at 1am
- There are no backups of media storage.
- Nextcloud backups are conducted daily at 2am
- Non-critical services are auto-updated daily at 3am (or according to their deployment's keel annotations). Users may experience service disruptions during this time.
- K3S is updated via system-upgrade-controller
- Nest host OSes are updated weekly on Sundays at 5am. Users may experience more serious service disruption at this time, however, updates/restarts are performed in a rolling fashion to minimize this.
- Access to all user-facing services is governed by Keycloak group.
- Users are granted access to the Matrix homeserver, Vaultwarden, forgejo, and the documentation you are about to write by default. All other services must be requested. Access to the default resources can be revoked.
- Requests for service access are made via Matrix bot. Users are to send a message to @access-bot:starling.mynest.love, using the !groups command to list the keycloak groups available, and the !request groupname command to request access. An admin will approve or deny their request.
- The Keycloak instance is set up such that it only accepts passkeys (i.e. passwordless). Other than an initial first time password, users will never be able to use a password to sign in. They must use a password manager that supports passkeys (such as the Vaultwarden instance I provide for them).
- Users must provide a valid email for the purposes of initial access and account recovery. Some downstream services may use the email address to send notifications if the user opts into them. I have no interest in selling people's info. The email stays secure. Otherwise, the only other info needed is a username in order to enroll.
- If you encounter an issue, join the "Admin" space and ask questions in the "Ask and Admin" room.
- At the time of writing, I am the only admin and developer. It may take some time to resolve issues.

As you are writing, if you require additional context or have questions, stop and ask me.
I intend to go back through the documentation to add screenshots and additional how-tos. As you are writing, if you recognize a good place for this, leave message starting with "TODO" so I can search it out and add it when you are done.