tux/gluebox-ops
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update 80_infrastructure/gitea-access.md

Browse Source
This commit is contained in:
tux
2026-01-26 10:08:29 -05:00
parent 5ae9008333
commit 16db3c8bd3
1 changed files with 39 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
80_infrastructure/gitea-access.md
View File

@ -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"**.