diff --git a/80_infrastructure/gitea-access.md b/80_infrastructure/gitea-access.md index 7e205e0..aa48179 100644 --- a/80_infrastructure/gitea-access.md +++ b/80_infrastructure/gitea-access.md @@ -1,50 +1,46 @@ # 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. +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. ## 1. Primary Access: SSH (Recommended) -Because Gitea runs as a system-level service under the `gitea` user, standard `git@` strings will fail. +This instance runs as the `gitea` system user. Standard `git@` strings will prompt for a password and fail. * **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..." + * *Expected Success:* "Hi there, [user]! You've successfully authenticated..." * **Clone Format:** ```bash git clone gitea@code.gluebox.com:tux/rsvp-system-core.git ``` ## 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. +Tokens only work correctly when Gitea can resolve its own internal loopback. * **Auth Header:** `Authorization: token ` * **Validation Test:** ```bash curl -H "Authorization: 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. +* **Troubleshooting:** If the response returns `"uid: 0"`, the server's `LOCAL_ROOT_URL` is likely missing or the token was generated before the server was properly configured. Generate a fresh token. ## 3. Mandatory Server Configuration (`app.ini`) -The following values in `/etc/gitea/app.ini` are critical for maintaining access: +The following values in `/etc/gitea/app.ini` are critical for maintaining access. If the server is moved or reinstalled, these must be verified: -| Section | Key | Required Value | Reason | +| Section | Key | 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. | +| `[server]` | `RUN_USER` | `gitea` | Matches the Ubuntu system user. | +| `[server]` | `OFFLINE_MODE` | `false` | Required for internal token verification. | +| `[server]` | `DISABLE_SSH` | `false` | Enables Gitea's internal SSH engine. | +| `[server]` | `LOCAL_ROOT_URL` | `http://localhost:3000/` | Fixes the "uid: 0" API bug. | -## 4. Mac Local Setup Fixes -If authentication hangs or defaults to a password prompt: +## 4. Maintenance & Troubleshooting +Since this instance uses the **Internal SSH Server**, Gitea manages keys in the database rather than a physical `authorized_keys` file. -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 +* **Keys not working?** Go to **Site Admin > Dashboard** and run: + * *Resynchronize pre-receive, update and post-receive hooks of all repositories.* +* **Auth Prompting for Password?** 1. Ensure your Mac's public key is added to **User Settings > SSH / GPG Keys**. + 2. Clear local Mac credential helpers: + `git config --global --unset credential.helper` \ No newline at end of file