docs: hosting documentation

DEPLOYMENT_PLUS/gemini-tips.md

@@ -0,0 +1,83 @@
+Several options exist for web-based file editors in Go, ranging from simple solutions to more feature-rich applications. Here are a few examples:
+
+• Simple Text Editor:
+	• A basic implementation involves using Go's html/template package to serve an HTML form with a textarea for editing. The server can then handle saving the content back to a file.
+	• This approach provides fundamental editing capabilities but lacks advanced features like syntax highlighting or real-time collaboration.
+
+• File Browser with Built-in Editor:
+	• Filebrowser is a web file manager written in Go that includes a built-in code editor with syntax highlighting for various languages.
+	• It offers functionalities like file management (upload, download, rename, delete), user authentication, and customization options.
+
+• WebEdit:
+	• WebEdit is an HTML5-based text editor designed for editing local files on a server. It aims to provide a more responsive editing experience compared to using SSH and command-line editors.
+
+• Go Playground:
+	• The Go Playground is a web service that allows users to run Go code in a sandboxed environment. While primarily for running code snippets, it can also be used for basic file editing.
+
+• GitHub.dev:
+	• GitHub.dev is a web-based editor that runs entirely in the browser. It allows users to navigate and edit files in GitHub repositories, offering features like syntax highlighting and source control integration.
+
+These options cater to different needs, from quick edits to comprehensive file management and code editing within a web environment. The choice of editor depends on the specific requirements of the project.
+
+---
+
+
+To implement a file editor using Go and HTMX, consider the following approach:
+
+• Backend (Go):
+	• File Handling: Implement functions to read, write, and update files on the server.
+	• Routing: Use a Go web framework (like net/http or chi) to define routes for handling file operations. For example:
+		• GET /edit/{filename}: Retrieve file content for editing.
+		• POST /save/{filename}: Save updated file content.
+
+	• Templating: Employ Go's html/template package or a templating engine like Templ to render HTML fragments for HTMX responses.
+
+• Frontend (HTMX and HTML):
+	• Display File Content: Create an HTML form with a <textarea> element to display and edit the file content.
+	• HTMX Integration: Use HTMX attributes to handle user interactions:
+		• hx-get on page load to fetch initial file content.
+		• hx-post on form submission to save changes.
+		• hx-target and hx-swap to update the UI after saving.
+
+	• Markdown Editor (Optional): Integrate a client-side Markdown editor like EasyMDE for enhanced editing capabilities.
+
+• Workflow:
+	• The user requests to edit a file (e.g., /edit/my-file.txt).
+	• The Go server reads the file and renders it within an HTML form.
+	• HTMX loads the form content into the page.
+	• The user edits the content and submits the form.
+	• HTMX sends a POST request to the /save endpoint.
+	• The Go server saves the changes and returns an updated HTML fragment.
+	• HTMX updates the UI with the response.
+
+• Code Example (Conceptual):
+
+    // Go (Backend)
+    func handleEditFile(w http.ResponseWriter, r *http.Request) {
+        filename := mux.Vars(r)["filename"]
+        content, err := os.ReadFile(filename)
+        if err != nil { /* handle error */ }
+        tmpl.ExecuteTemplate(w, "edit_form.html", map[string]string{"Filename": filename, "Content": string(content)})
+    }
+
+    func handleSaveFile(w http.ResponseWriter, r *http.Request) {
+        filename := mux.Vars(r)["filename"]
+        content := r.FormValue("content")
+        err := os.WriteFile(filename, []byte(content), 0644)
+        if err != nil { /* handle error */ }
+        // Return updated HTML or success message
+        fmt.Fprint(w, "<div class='success'>File saved successfully!</div>")
+    }
+
+    <!-- HTML (Frontend - edit_form.html) -->
+    <form hx-post="/save/{{.Filename}}" hx-target="#file-editor" hx-swap="outerHTML">
+        <textarea name="content">{{.Content}}</textarea>
+        <button type="submit">Save</button>
+    </form>
+    <div id="file-editor"></div>
+
+• Templ vs standard templates:
+	• Templ offers better type safety, but it introduces extra steps of generating templ files and then compiling the program before checking template changes. [1]
+	• Standard templates allow to check template changes just by saving the template file and reloading the page.
+
+[1] https://www.reddit.com/r/htmx/comments/1ams8xi/gohtmx_templ_vs_templates/

DEPLOYMENT_PLUS/hosting-base.md

@@ -0,0 +1,111 @@
+# Base Hosting Setup: Syncthing & Caddy
+
+This document contains the shared installation and configuration steps for Syncthing and Caddy that are used across multiple hosting scenarios (new setup, final deployment, etc.).
+
+**See also:**
+- **hosting-new.md** — Full, detailed guide for new VPS setup (canonical reference)
+- **hosting-final.md** — Quick-start guide with links to full instructions
+- **hosting-gemini.md** — Gemini-specific hosting notes
+
+---
+
+## Install Syncthing
+
+Following: <https://idroot.us/install-syncthing-ubuntu-24-04>
+
+```sh
+sudo apt update -y && sudo apt upgrade -y && sudo apt autoremove
+
+sudo apt install gnupg2 curl apt-transport-https -y
+
+# Follow instructions from: https://apt.syncthing.net
+sudo mkdir -p /etc/apt/keyrings
+sudo curl -L -o /etc/apt/keyrings/syncthing-archive-keyring.gpg https://syncthing.net/release-key.gpg
+# Add the "stable" channel to your APT sources:
+echo "deb [signed-by=/etc/apt/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable" | sudo tee /etc/apt/sources.list.d/syncthing.list
+sudo apt update
+sudo apt install syncthing
+syncthing --version
+
+# Warning: consider making a non-root user for the application in a future iteration
+sudo systemctl enable [email protected]
+sudo systemctl start [email protected]
+sudo systemctl status [email protected]
+
+# Keep SSH, turn on web, and allow ports for Syncthing
+sudo ufw allow ssh && sudo ufw allow http && sudo ufw allow https && \
+    sudo ufw allow 22000/tcp && sudo ufw allow 22000/udp && sudo ufw allow 21027/udp && sudo ufw enable && sudo ufw status
+```
+
+**Configure Syncthing (from local laptop):**
+
+```sh
+# Port-Forward the UI to Sync (run on Laptop)
+ssh -L 9998:localhost:8384 ubuntu-4gb-hel1-1
+# Copy Laptop Device ID, accept from laptop, then edit the connection to check all three options (introducer, share, etc.), and confirm one more time from laptop
+# <https://docs.syncthing.net/intro/getting-started.html#configuring>
+```
+
+---
+
+## Install Caddy
+
+Following: <https://caddyserver.com/docs/install#debian-ubuntu-raspbian>
+
+```sh
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update
+sudo apt install caddy
+```
+
+---
+
+## Configure Caddy
+
+Following: <https://caddyserver.com/docs/quick-starts/https>
+
+```sh
+sudo ufw allow OpenSSH && sudo ufw allow http && sudo ufw allow https && sudo ufw enable && sudo ufw status
+# Check that the domain is configured
+curl "https://cloudflare-dns.com/dns-query?name=yak-shears.kyleking.me&type=A" \
+  -H "accept: application/dns-json"
+
+tee "Caddyfile" > /dev/null <<'EOF'
+{
+    email [email protected]  # Recommended for Let's Encrypt notifications
+}
+
+yak-shears.kyleking.me {
+    # 8384 for Syncthing fails because of host check errors as designed
+    reverse_proxy localhost:8084 {
+        header_up Host {host}
+        header_up X-Real-IP {remote_host}
+        header_up X-Forwarded-For {remote_host}
+        header_up X-Forwarded-Proto {scheme}
+    }
+    header {
+        # (HSTS): Forces browsers to always use HTTPS.
+        Strict-Transport-Security "max-age=31536000; includeSubDomains"
+        # Prevents browsers from MIME-sniffing
+        X-Content-Type-Options "nosniff"
+        # Helps prevent clickjacking attacks.
+        X-Frame-Options "DENY"
+        # Controls how much referrer information is sent with requests.
+        Referrer-Policy "same-origin"
+        # Content-Security-Policy "default-src 'self';" # Customize as needed
+    }
+}
+EOF
+
+# Example reviewing logs:
+# sudo journalctl -u caddy --no-pager
+```
+
+---
+
+## See Also
+
+- Caddy documentation: <https://caddyserver.com/docs/running>
+- Syncthing documentation: <https://docs.syncthing.net/>

DEPLOYMENT_PLUS/hosting-final.md

@@ -0,0 +1,69 @@
+# Hosting — Quick-Start Guide
+
+**This is a quick-start overview. For detailed instructions, see the full guides below.**
+
+---
+
+## Documentation Map
+
+- **hosting-new.md** — **Canonical full reference guide** with all setup details (Syncthing, Caddy, FileBrowser, Traefik history)
+- **hosting-base.md** — Shared installation and configuration for Syncthing and Caddy (referenced by other guides)
+- **hosting-final.md** — This quick-start (you are here)
+- **hosting-gemini.md** — Gemini-specific hosting notes
+
+---
+
+## Quick Setup Checklist
+
+### Prerequisites
+
+Selected VPS for similarity to local usage and Hetzner because of cost and IaC support:
+- <https://registry.terraform.io/providers/hetznercloud/hcloud/latest/docs/resources/server>
+- See notes on deployment saved in 1Password for Hetzner
+- More SSH Key info: <https://community.hetzner.com/tutorials/howto-ssh-key>
+
+### Steps
+
+1. **Install Syncthing**
+   Follow the complete instructions in **hosting-base.md** — Install Syncthing section
+
+2. **Install and Configure Caddy**
+   Follow the complete instructions in **hosting-base.md** — Install Caddy and Configure Caddy sections
+
+3. **Set up FileBrowser** (optional, for file management UI)
+   See **hosting-new.md** — FileBrowser section for details
+
+4. **Additional Configuration Details**
+   Refer to **hosting-new.md** for:
+   - IPv6 setup notes
+   - Hetzner Web Console access via Rescue/Reset
+   - UFW firewall rules and persistence issues
+   - FileBrowser systemd service configuration
+
+---
+
+## Common Tasks
+
+| Task | Location |
+|------|----------|
+| Syncthing setup | hosting-base.md → Install Syncthing |
+| Caddy installation & config | hosting-base.md → Install Caddy |
+| FileBrowser setup | hosting-new.md → FileBrowser |
+| UFW firewall issues | hosting-new.md → TODO section |
+| Full reference | hosting-new.md |
+
+---
+
+## Notes
+
+- The ufw rules may reset on VPS boot; see hosting-new.md TODO section for workarounds
+- For Caddy running as a service: <https://caddyserver.com/docs/running>
+- Consider using NixOS for reproducible deployments: <https://wrycode.com/reproducible-syncthing-deployments>
+
+---
+
+## Related Docs
+
+- hosting-gemini.md — Gemini-specific configuration
+- hosting-base.md — Shared setup instructions
+- hosting-new.md — Full reference guide