====== Forgejo ======

[[http://https://forgejo.org/|Forgejo]] is a self-hosted lightweight software forge.
Easy to install and low maintenance, it just does the job. It is a nice web gui for GIT. It is actually much more and allows for GIT fine tuning of remote repositories and access control. It can be used to version-control any kind of sources, including text documents and scripts.

Forgejo is the evolution of [[services:gitea|GITea]], from which it forked some time ago out of concerns for monetization strategies and ambiguous behaviour from GITEA parent company.

===== Installation =====

While you could deploy forgejo using a container, it's really overkill as Forgejo is provided as a single binary that you only have to download and run.

On Gentoo, if you have already installed [[https://git-scm.com/git]], you will already have a **git** user that can be used to deploy Forgejo. If you have not installed git, emerge it now:
<code bash>
emerge -vp git
</code>

You need to choose where you want to store your Forgejo repositories and data, and i suggest not to locate it under the git home folder, but on a dedicated data folder which i will call **/data/git-repos**, so as root create it now, as well as the logs folder:
<code bash>
mkdir /data/git-repos
chown git:git /data/git-repos
mkdir /var/log/forgejo
chown git:git /var/log/forgejo
</code>

You want to move repositories and data and config to your RAID drive, this can be done by changing user **git** home folder:
<code bash>
usermod -d /data/daemons/forgejo -m git
</code>

Now, find your preferred build on [[https://codeberg.org/forgejo/forgejo/releases|Forgejo releases page on Codeberg]], and download it. I prefer to put it into a //bin// folder:
<code bash>
su - git
wget https://codeberg.org/forgejo/forgejo/releases/download/vX.Y.Z/forgejo-X.Y.Z-linux-amd64
chmod +x forgejo-X.Y.Z-linux-amd64
ln -s forgejo-X.Y.Z-linux-amd64 forgejo
</code>
The symlink is useful to simplify the startup init script later on.

You need an initial **app.ini** for Forgejo to operate, and it needs to be located under **/data/daemons/forgejo/custom/conf** (unless you want to change location with --custom-path), so create it starting from the following basic defaults:
<file - app.ini>
APP_NAME = My ForgeJo
RUN_USER = git
WORK_PATH = /data/daemons/forgejo

[server]
ROOT_URL = https://home.mydomain.com/forgejo/
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3001
LFS_JWT_SECRET = <<< secret >>>
SSH_DOMAIN = home.mydomain.com
DOMAIN = home.mydomain.com
APP_DATA_PATH = /data/git-repos/

[database]
DB_TYPE = sqlite3
HOST = 127.0.0.1:3306
NAME = forgejo
USER = root
PATH = /data/git-repos/forgejo.db
LOG_SQL = false

[log]
MODE = file
LEVEL = info
ROOT_PATH = /var/log/forgejo

[repository]
ROOT = /data/git-repos/repositories

[lfs]
PATH = /data/git-repos/lfs
</file>

i have omitted most of the lines, those are only the ones you need to specifically edit. Forgejo itself will add the others after first run. Adapt paths and port to your needs!

You can now manually start Forgejo:
<code bash>
./forgejo
</code>

One last step is to ensure your **app.ini** is safe if you reinstlal Forgejo. Since i do backup the git repos folder but not the daemons folder, i just move it there and link it back:
<code bash>
cd ~/custom/conf/ 
mv app.ini /data/git-repos
ln -s /data/git-repos/app.ini .
</code>

Note that your **git** user //~/.ssh// must exist and the permission chain into it must be set properly!
The /data/daemons/git must be **750** and the /data/daemons/git/.ssh should be **700** (but 750 should do the trick as well).

==== Reverse Proxy setup ====

And setup NGINX reverse proxy by creating **forgejo.conf**:
<file forgejo.conf>
  location /forgejo/ {
        client_max_body_size 512M;

        # make nginx use unescaped URI, keep "%2F" as is
        rewrite ^ $request_uri;
        rewrite ^/forgejo(/.*) $1 break;
        proxy_pass http://127.0.0.1:3001$uri;

        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-WEBAUTH-USER $remote_user;
        proxy_set_header Authorization "";
    }
</file>
(refer to [[selfhost:nginx|The Reverse Proxy concept]] for more details on this)

Now your remote URLs are in the following format:
<code>
 For SSH urls: ssh://git@home.mydomain.com:ssh_port/user/repo.git
</code>

== Using Reverse Proxy authentication ===

Forgejo support reverse proxy authentication. The above NGINX config already set it up, but you need to open GITea settings and go to **Authentication Sources** and replace the existing one (or add a new one) ad **PAM_Auth**. The settings you need are:
  * pam_service_name: system-local-login

that's it. This will work with your SSO.

==== Autostart ====

Drop the following init script to **/etc/init.d/forgejo**:
<file - forgejo>
#!/sbin/openrc-run
# Copyright 2016-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

description="ForgeJo, a self-hosted Git service"

command="/data/daemons/forgejo/forgejo"
command_args=""
command_background="true"
command_user="git:git"
error_log="/var/log/forgejo/forgejo.err"
pidfile="/run/forgejo.pid"
</file>

Make it executable, set to run on default runlevel and run it now:
<code bash>
chmod +x /etc/init.d/forgejo
rc-update add forgejo default
/etc/init.d/forgejo start
</code>



==== Updates ====

Just stop the service, download new binary, point symnlink to new binary, restart the service!