docs: add Forgejo instance setup guide
This commit is contained in:
parent
e65169e4e0
commit
e10bf21b86
1 changed files with 218 additions and 0 deletions
218
forgejo-instance-setup.md
Normal file
218
forgejo-instance-setup.md
Normal file
|
|
@ -0,0 +1,218 @@
|
||||||
|
# Forgejo Instance Setup Guide
|
||||||
|
|
||||||
|
This document describes how to set up and work with a Forgejo instance from scratch.
|
||||||
|
|
||||||
|
## 1. Create an Account
|
||||||
|
|
||||||
|
### Via Web UI
|
||||||
|
1. Go to your Forgejo instance URL (e.g., `https://vmd185580.tailf38284.ts.net`)
|
||||||
|
2. Click **Sign Up** or **Register**
|
||||||
|
3. Fill in:
|
||||||
|
- Username (e.g., `nazim`)
|
||||||
|
- Email address
|
||||||
|
- Password
|
||||||
|
4. Complete CAPTCHA if required
|
||||||
|
5. Check email for verification link (if email is enabled)
|
||||||
|
|
||||||
|
### Via API (Admin-only)
|
||||||
|
Regular users cannot create accounts via API. Contact an admin or use the web UI.
|
||||||
|
|
||||||
|
## 2. Install `tea` CLI
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
```bash
|
||||||
|
brew install tea-org/tea/tea
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linux (amd64)
|
||||||
|
```bash
|
||||||
|
# Download latest release
|
||||||
|
curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-amd64.tar.gz | tar xz -C /tmp
|
||||||
|
sudo mv /tmp/tea /usr/local/bin/
|
||||||
|
sudo chmod +x /usr/local/bin/tea
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linux (arm64)
|
||||||
|
```bash
|
||||||
|
curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-arm64.tar.gz | tar xz -C /tmp
|
||||||
|
sudo mv /tmp/tea /usr/local/bin/
|
||||||
|
sudo chmod +x /usr/local/bin/tea
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verify Installation
|
||||||
|
```bash
|
||||||
|
tea --version
|
||||||
|
# Expected: Version: [1m0.12.0[0m golang: 1.25.7 go-sdk: v0.23.2
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Configure Login
|
||||||
|
|
||||||
|
### Get a Personal Access Token
|
||||||
|
|
||||||
|
1. Log in to your Forgejo instance via web UI
|
||||||
|
2. Go to **Settings** → **Application**
|
||||||
|
3. Click **Add Access Token**
|
||||||
|
4. Fill in:
|
||||||
|
- Token name: e.g., `tea-cli`
|
||||||
|
- Select scopes (minimum required):
|
||||||
|
- `read:user` — View user profile
|
||||||
|
- `write:repository` — Create and manage repos
|
||||||
|
- Click **Generate Token**
|
||||||
|
5. Copy the generated token (you won't see it again!)
|
||||||
|
|
||||||
|
### Save to `tea` Config
|
||||||
|
|
||||||
|
The config file is at:
|
||||||
|
- Linux/macOS: `~/.config/tea/config.yml`
|
||||||
|
- Windows: `%AppData%\tea\config.yml`
|
||||||
|
|
||||||
|
#### Example Config
|
||||||
|
```yaml
|
||||||
|
logins:
|
||||||
|
- name: vmd185580
|
||||||
|
url: https://vmd185580.tailf38284.ts.net
|
||||||
|
token: <your-generated-token-here>
|
||||||
|
default: true
|
||||||
|
ssh_host: vmd185580.tailf38284.ts.net
|
||||||
|
ssh_key: ""
|
||||||
|
insecure: false
|
||||||
|
user: nazim
|
||||||
|
created: <unix-timestamp>
|
||||||
|
preferences:
|
||||||
|
editor: false
|
||||||
|
flag_defaults:
|
||||||
|
remote: ""
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Get Current Unix Timestamp
|
||||||
|
```bash
|
||||||
|
date +%s
|
||||||
|
# Example output: 1776359800
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Connection
|
||||||
|
```bash
|
||||||
|
tea whoami
|
||||||
|
# Expected output:
|
||||||
|
# # nazim
|
||||||
|
# Follower Count: 0, Following Count: 0, Starred Repos: 0
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Common Tasks
|
||||||
|
|
||||||
|
### List Logins
|
||||||
|
```bash
|
||||||
|
tea login list
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create a Repository
|
||||||
|
```bash
|
||||||
|
tea repos create --name my-repo \
|
||||||
|
--description "My project" \
|
||||||
|
--init \
|
||||||
|
--license mit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Clone a Repository
|
||||||
|
```bash
|
||||||
|
tea clone nazim/my-repo
|
||||||
|
# or
|
||||||
|
git clone https://vmd185580.tailf38284.ts.net/nazim/my-repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
### List Repositories
|
||||||
|
```bash
|
||||||
|
tea repos list --mine
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create an Issue
|
||||||
|
```bash
|
||||||
|
tea issues create --repo nazim/my-repo \
|
||||||
|
--title "Bug: Something is wrong" \
|
||||||
|
--body "Steps to reproduce..."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create a Pull Request
|
||||||
|
```bash
|
||||||
|
tea pr create --repo nazim/my-repo \
|
||||||
|
--title "Fix: Something was wrong" \
|
||||||
|
--body "This PR fixes the issue." \
|
||||||
|
--head feature-branch
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. SSH Access (Optional)
|
||||||
|
|
||||||
|
If you want to use SSH instead of HTTPS:
|
||||||
|
|
||||||
|
### Generate SSH Key
|
||||||
|
```bash
|
||||||
|
ssh-keygen -t ed25519 -C "nazim@openclaw.ai" -f ~/.ssh/vmd185580
|
||||||
|
```
|
||||||
|
|
||||||
|
### Add Public Key to Forgejo
|
||||||
|
```bash
|
||||||
|
cat ~/.ssh/vmd185580.pub
|
||||||
|
# Copy output to Forgejo → Settings → SSH Keys
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configure Git SSH Host
|
||||||
|
```bash
|
||||||
|
# Add to ~/.ssh/config
|
||||||
|
Host vmd185580.tailf38284.ts.net
|
||||||
|
HostName vmd185580.tailf38284.ts.net
|
||||||
|
User git
|
||||||
|
Port 222
|
||||||
|
IdentityFile ~/.ssh/vmd185580
|
||||||
|
```
|
||||||
|
|
||||||
|
### Clone via SSH
|
||||||
|
```bash
|
||||||
|
git clone ssh://git@vmd185580.tailf38284.ts.net:222/nazim/my-repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Troubleshooting
|
||||||
|
|
||||||
|
### Token Scope Errors
|
||||||
|
If you see `token does not have at least one of required scope(s)`, add more scopes to your token via Forgejo web UI → Settings → Application.
|
||||||
|
|
||||||
|
### Connection Timeouts
|
||||||
|
- Check if the instance is reachable: `ping vmd185580.tailf38284.ts.net`
|
||||||
|
- Check TLS: `curl -v https://vmd185580.tailf38284.ts.net`
|
||||||
|
- Check API: `curl https://vmd185580.tailf38284.ts.net/api/v1/version`
|
||||||
|
|
||||||
|
### Wrong Login Used
|
||||||
|
Set the default login in config or use `--login` flag:
|
||||||
|
```bash
|
||||||
|
tea whoami --login vmd185580
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7. Scope Reference
|
||||||
|
|
||||||
|
| Scope | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `read:user` | View user profile and followers |
|
||||||
|
| `write:repository` | Create, update, delete repositories |
|
||||||
|
| `read:repository` | Read repository contents (public) |
|
||||||
|
| `write:organization` | Manage organizations |
|
||||||
|
| `admin:org` | Admin-level org access |
|
||||||
|
|
||||||
|
## 8. Example Workflow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Create repo
|
||||||
|
tea repos create --name krallen-skills \
|
||||||
|
--description "Forgejo instance skills" \
|
||||||
|
--init
|
||||||
|
|
||||||
|
# 2. Clone locally
|
||||||
|
git clone https://vmd185580.tailf38284.ts.net/nazim/krallen-skills.git
|
||||||
|
|
||||||
|
# 3. Add content
|
||||||
|
cd krallen-skills
|
||||||
|
echo "# Krallen Skills" > README.md
|
||||||
|
|
||||||
|
# 4. Push changes
|
||||||
|
git add .
|
||||||
|
git commit -m "Initial commit"
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
Loading…
Add table
Reference in a new issue