From 16db3c8bd3ffb4309417bd96a67d45a506a9da36 Mon Sep 17 00:00:00 2001
From: tux <tux@gluebox.com>
Date: Mon, 26 Jan 2026 10:08:29 -0500
Subject: [PATCH] Update 80_infrastructure/gitea-access.md

---
 80_infrastructure/gitea-access.md | 94 +++++++++++++------------------
 1 file changed, 39 insertions(+), 55 deletions(-)

diff --git a/80_infrastructure/gitea-access.md b/80_infrastructure/gitea-access.md
index 45f336e..7e205e0 100644
--- a/80_infrastructure/gitea-access.md
+++ b/80_infrastructure/gitea-access.md
@@ -1,66 +1,50 @@
-# 📄 Revised `gitea-access.md`
+# Gitea Access & Authentication Guide
 
----
+This document defines the standard for accessing the Gluebox Gitea instance. Following these rules prevents the "uid: 0" (User Not Found) and "SSH Disabled" errors encountered during initial setup.
 
-## 1. The SSH Connection Rule
+## 1. Primary Access: SSH (Recommended)
+Because Gitea runs as a system-level service under the `gitea` user, standard `git@` strings will fail.
 
-Because this instance runs as the `gitea` user (not `git`), all SSH clones **must** use the `gitea` prefix.
+* **SSH Username:** `gitea`
+* **Host:** `code.gluebox.com`
+* **Verification:** Run `ssh -T gitea@code.gluebox.com` from your Mac. 
+    * *Success:* "Hi there, [user]! You've successfully authenticated..."
+* **Clone Format:**
+    ```bash
+    git clone gitea@code.gluebox.com:tux/rsvp-system-core.git
+    ```
 
-- ❌ **WRONG:**
+## 2. Fallback Access: HTTPS & API Tokens
+If SSH is unavailable, use a Personal Access Token (PAT). Note that Gitea requires internal loopback to be configured for tokens to validate correctly.
 
-  ```
-  git@code.gluebox.com:tux/repo.git
-  ```
+* **Auth Header:** `Authorization: token <YOUR_TOKEN>`
+* **Validation Test:**
+    ```bash
+    curl -H "Authorization: token <TOKEN>" [https://code.gluebox.com/api/v1/user](https://code.gluebox.com/api/v1/user)
+    ```
+* **Troubleshooting:** If the response returns `"uid: 0"`, the server's `LOCAL_ROOT_URL` is likely missing or misconfigured.
 
-- ✅ **CORRECT:**
+## 3. Mandatory Server Configuration (`app.ini`)
+The following values in `/etc/gitea/app.ini` are critical for maintaining access:
 
-  ```
-  gitea@code.gluebox.com:tux/repo.git
-  ```
+| Section | Key | Required Value | Reason |
+| :--- | :--- | :--- | :--- |
+| `[server]` | `RUN_USER` | `gitea` | Defines the SSH system user. |
+| `[server]` | `OFFLINE_MODE` | `false` | Enables internal API/Avatar resolution. |
+| `[server]` | `DISABLE_SSH` | `false` | Enables the Gitea SSH wrapper. |
+| `[server]` | `LOCAL_ROOT_URL` | `http://localhost:3000/` | Fixes the "uid: 0" token verification bug. |
 
----
 
-## 2. Required Server Settings (`app.ini`)
 
-For authentication to work correctly across Git and API access, the following must be set:
+## 4. Mac Local Setup Fixes
+If authentication hangs or defaults to a password prompt:
 
-```ini
-OFFLINE_MODE     = false     # Ensures internal host resolution works
-DISABLE_SSH      = false     # Enables the SSH handshake
-LOCAL_ROOT_URL   = http://localhost:3000/   # Critical for internal token verification
-```
-
----
-
-## 3. macOS Setup Flow
-
-### 🔑 Generate SSH Key
-
-```bash
-ssh-keygen -t ed25519
-```
-
-### 🔗 Add to Gitea
-
-Paste your `.pub` file content into:  
-**User Settings → SSH / GPG Keys**
-
----
-
-### ✅ Verify Connection
-
-```bash
-ssh -T gitea@code.gluebox.com
-```
-
-Expected response:
-
-> "Hi there, [username]!"
-
----
-
-### 📥 Clone Command
-
-```bash
-git clone gitea@code.gluebox.com:tux/rsvp-system-core.git
-```
+1.  **Clear Mac Keychain interference:**
+    ```bash
+    git config --global --unset credential.helper
+    ```
+2.  **Fix SSH Key Permissions:**
+    ```bash
+    chmod 700 ~/.ssh && chmod 600 ~/.ssh/id_ed25519
+    ```
+3.  **Resync (Server Side):** If keys are added in the UI but rejected by the server, go to **Site Admin > Dashboard** and run **"Resynchronize SSH authorized_keys file"**.
\ No newline at end of file