#+title: Forgejo
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="_share/media/css/computer.css" />
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="_share/media/css/org-media-sass/content-overview.css" />
#+OPTIONS: H:6

* links
- [[./toc.org][TOC - Home System]]

* Hardware

* Forgejo on Raspberry Pi

** Configuration Summary
*** Instance Details
| Property             | Value                            |
|----------------------+----------------------------------|
| URL                  | https://forgejo.ronnyabraham.com |
| SSH Server Port      | 222                              |
| Web Server Port      | 3000                             |
| Repository Root Path | /data/git/repositories           |
| Docker User          | git                              |

*** Users
| Role       | Username   | Password     | Email                   |
|------------+------------+--------------+-------------------------|
| Admin      | git-admin  | 2reishit2ara | ronny.abraham@ymail.com |
| Developer  | ronnygit   | 2reishit2ara | ronny.coder@gmail.com   |


** Data Drive & Volumes

*** Physical Storage & Mount Info️

| Property           | Value                                |
|--------------------+--------------------------------------|
| Physical Mount     | /mnt/git                             |
| Logical Bind Mount | /srv/git                             |
| Device             | /dev/sdb1                            |
| Filesystem Type    | ext4                                 |
| Label              | gitdisk                              |
| UUID               | 649f82e9-cfc0-4725-b260-d40f413bd0c3 |
| Used for           | Forgejo repository storage           |

*** fstab Entries
#+begin_src conf
 UUID=649f82e9-cfc0-4725-b260-d40f413bd0c3 /mnt/git ext4 defaults,noatime 0 2
 /mnt/git /srv/git none bind 0 0
#+end_src

*** Mapping

To separate application configuration from repository data, the Forgejo Docker container uses specific internal paths. We map our host directories accordingly for clarity and ease of maintenance.

**** Folder Layout

#+begin_example
/mnt/storage/compose/docker/forgejo  ← holds docker-compose.yml

/srv/git/
├── data/      ← holds all persistent repo data (repositories, issues, uploads)
└── config/    ← holds configuration files (e.g. app.ini)
#+end_example

This split layout allows easy backup, inspection, and version control of the Forgejo configuration without interfering with large and changing repository data.

**** Volume Mapping

| Host path         | Container path         | Purpose                        |
|-------------------+------------------------+--------------------------------|
| /srv/git/data     | /data/data             | Git repos, issues, uploads     |
| /srv/git/config   | /data/gitea/conf       | app.ini, server configuration  |

Make sure both folders on the host (`/srv/git/data` and `/srv/git/config`) are owned by the correct user (e.g. UID 1000), and match the container’s expectations.

*** File Setup

| Component | Path                                | Purpose                   |
|-----------+-------------------------------------+---------------------------|
| Nginx     | /etc/nginx/sites-available/forgejo  | reverse proxy for Forgejo |
| Docker    | /mnt/storage/docker/compose/forgejo | docker compose file       |


** Docker Setup
#+INCLUDE: "docker.org::#docker-forgejo" :only-contents t


** Nginx

*** Site Configuration


#+INCLUDE: "nginx.org::#forgejo-conf" :only-contents t

*** Enable Site & Restart
#+begin_src bash
sudo ln -s /etc/nginx/sites-available/forgejo /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
#+end_src

*** Enable HTTPS with Certbot
#+begin_src bash
sudo certbot --nginx -d git.ronnyabraham.com
#+end_src

** First-Time Setup
- Visit: https://forgejo.ronnyabraham.com
- Create the `git-admin` user and initialize your first repository.

* Git Repository Management

** Push an Existing Local Repo to Forgejo

#+begin_src bash
cd ~/your-local-project
git remote add origin ssh://git@forgejo.ronnyabraham.com:222/ronny/<repo-name>.git
git push -u origin main
#+end_src

** Mirror from Bitbucket to Forgejo
#+begin_src bash
git clone --mirror git@bitbucket.org:your-username/your-repo.git
cd your-repo.git
git remote set-url --push origin ssh://git@forgejo.ronnyabraham.com:222/ronny/your-repo.git
git push --mirror
cd ..
rm -rf your-repo.git
#+end_src



** Example: Uploading savage-lands Repo

*** Repository Info
- Repo Name: savage-lands
- Owner: ronnygit
- Remote: ssh://git@forgejo.ronnyabraham.com:222/ronnygit/savage-lands.git

*** Commands
#+begin_src bash
git remote remove origin  # if already exists
git remote add origin ssh://git@forgejo.ronnyabraham.com:222/ronnygit/savage-lands.git
git push -u origin main
#+end_src

* How to Check Repository Access for a User via Token

To verify whether a Forgejo user (e.g. `ronnygit`) has access to a specific repository, you can use a Personal Access Token (PAT) to query the Forgejo API. This helps confirm push/pull permissions and identify missing access rights.

** Step-by-Step: Create a Personal Access Token

1. Log in to Forgejo as the user: `ronnygit`
2. Go to: https://forgejo.ronnyabraham.com/user/settings/applications
3. Click "Generate New Token"
4. Name it: api-debug
5. Enable these scopes:
   - repository - read/write access to repositories
   - organization - access to organization/team membership
   - user - user info access
   - issue - access to issues API
   - (Do not enable package or activitypub unless needed)
6. Click "Generate" and save the token immediately

** Use the Token to Query Repository Access

Example command to check access to the `project` repository under `django-repositories`:

#+begin_src bash
curl -H "Authorization: token edea73cc91dbae359d89eb0e644ef2c97f3aedf0" \
     https://forgejo.ronnyabraham.com/api/v1/repos/django-repositories/project
#+end_src

Expected output:
#+begin_example
"permissions": {
  "admin": false,
  "push": true,
  "pull": true
}
#+end_example

HTTP error meanings:
- 404 - repository does not exist or is private with no access
- 403 - repository exists, but you do not have permission
- 401 - token is invalid or expired

** Token Details

| Property     | Value                                                             |
|--------------+-------------------------------------------------------------------|
| Token Owner  | ronnygit                                                          |
| Token Name   | api-debug                                                         |
| Token Value  | edea73cc91dbae359d89eb0e644ef2c97f3aedf0                          |
| Scopes       | repository, organization, user, issue                             |
| Created At   | Apr 17, 2025                                                      |
| Purpose      | Used to verify access to django-repositories/project.git         |

** Scope Overview

| Scope         | Required | Purpose                                                   |
|---------------+----------+-----------------------------------------------------------|
| repository    | Yes      | Access to repository APIs (push, pull, branches, etc.)    |
| organization  | Yes      | View team and organization membership                     |
| user          | Optional | View user info and preferences                            |
| issue         | Optional | Access issues (create, read, update, comment)             |
| package       | No       | Access to package registry (e.g., Docker, npm, PyPI)      |
| activitypub   | No       | Enable federation features (e.g., Mastodon integration)   |