Forgejo

Forgejo is a self-hosted git forge similar to GitHub. Forgejo is a fork of Gitea, which is a fork of Gogs.

Installing Forgejo is useful for two unrelated purposes:

Self-hosting your own git repositories.
Providing an OAuth2 identity service for your organization, facilitating single-sign on to all of your apps via Traefik’s forward-auth middleware.

Forgejo is fundamental infrastructure

You don’t need to install Forgejo on every server you make, but having at least one instance in your domain is recommended.

Even if you (or your users) have no need for storing git repositories, Forgejo is part of the fundamental infrastructure of securing other d.rymcg.tech apps via OAuth2. You can authenticate and authorize your users to access your apps via their Forgejo account (sentry authorization), see the next chapter: Traefik Forward Auth.

Configure Forgejo

Run this on the Raspberry Pi

pi make forgejo config

Configure the domain name and service description:

(stdout)

FORGEJO_TRAEFIK_HOST: Enter your forgejo domain name (eg. git.example.com)

: git.pi.example.com

APP_NAME: Enter the service description (eg. "git thing")

: pi5 git hosting

? Do you want to enable sentry authorization in front of this app (effectively making the entire site private)?
> No
  Yes, with Mutual TLS (mTLS)

Install Forgejo

Run this on the Raspberry Pi

pi make forgejo install

Add a new route on the sentry

Run this on your Raspberry Pi

sentry route set pi git.pi.example.com

Tip

You may also create the route interactively through the Traefik config menu.

Finish Forgejo installation

Immediately open the Foregjo application to finish the installation. Open your web browser to https://git.pi.example.com.

This should show a page with the title Initial configuration at the top. The only thing you need to change on this page is the admin credentials found at the bottom (all of other settings are instead derived from the environment variables found in the Forgejo .env_{CONTEXT}_{INSTANCE} file created by d.rymcg.tech):

You should create a dedicated admin account, separate from your personal account.
Click Administrator account settings to expand the section.
Enter the Adminstrator username: root
Enter the admin email address.
Enter a secure passphrase and confirmation.
Click the Install Forgejo button at the very bottom.

Once logged in as root, you can create additional user accounts from the account icon in the top right, which expands a menu.

Click Site adminstration.
Click Identity & access.
Click User accounts.

Click Create User Account and create your own personal account.
Log out of the root account and test logging into the new account.

Which account to use?

You should use the root account for creating new OAuth2 apps and for creating new users.
You should use your personal account for storing your git repositories and for your identity when logging into other apps.

Enable access to repositories by SSH

By default, Forgejo only supports cloning its hosted git repositories via HTTPS. To allow cloning by SSH, you must enable the Traefik SSH entrypoint:

Enable the Traefik SSH entrypoint

Run this on the Raspberry Pi

pi make traefik config

(stdout)

? Traefik:
> Config
  Install (make install)
  Admin
  Exit (ESC)

? Traefik Configuration:
  Traefik user
> Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / Wireguard)
  Error page template
v Logging level

? Traefik entrypoint config
  Show enabled entrypoints
> Configure stock entrypoints
  Configure custom entrypoints

? Select entrypoint to configure:
^ websecure : HTTPS (TLS encrypted HTTP)
  web_plain : HTTP (unencrypted; specifically NOT redirected to websecure; must use different port than web)
  mqtt : MQTT (mosquitto) pub-sub service
> ssh : SSH (forgejo) git (ssh) entrypoint
  xmpp_c2s : XMPP (ejabberd) client-to-server entrypoint
  xmpp_s2s : XMPP (ejabberd) server-to-server entrypoint
v mpd : Music Player Daemon (mopidy) control entrypoint

> Do you want to enable the ssh entrypoint? Yes

TRAEFIK_SSH_ENTRYPOINT_HOST: Enter the host ip address to listen on (0.0.0.0 to listen on all interfaces) (eg. 0.0.0.0)

: 0.0.0.0

TRAEFIK_SSH_ENTRYPOINT_PORT: Enter the host port to listen on (eg. 2222)

: 2222

? Is this entrypoint downstream from another trusted proxy?
> No, clients dial directly to this server. (Turn off Proxy Protocol)
  Yes, clients are proxied through a trusted server. (Turn on Proxy Protocol)

Do not enable Proxy Protocol

Do not enable Proxy Protocol, because it is not supported by SSH.

Press ESC three times to go back to the main menu, then re-install Traefik:

(stdout)

? Traefik:
  Config
> Install (make install)
  Admin
  Exit (ESC)

Once reinstalled, press ESC to exit the config tool.

Create an entrypoint on the sentry

Run this on the Raspberry Pi

sentry make traefik config

(stdout)

? Traefik:
> Config
  Install (make install)
  Admin
  Exit (ESC)

? Traefik Configuration:
  Traefik user
> Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / Wireguard)
  Error page template
v Logging level

? Custom Entrypoints: 

? Traefik entrypoint config
  Show enabled entrypoints
  Configure stock entrypoints
> Configure custom entrypoints

? Custom Entrypoints:
  List custom entrypoints
> Add new custom entrypoint
  Remove custom entrypoints

Adding a custom TCP/UDP entrypoint -

- Make sure to enable the port in all upstream firewalls.
- Make sure each entrypoint has a unique lower-case one-word name.

Enter the new entrypoint name:

: forgejo

Enter the entrypoint listen address:

: 0.0.0.0

Enter the entrypoint port:

: 2222

Enter the protocol (tcp or udp):

: tcp

? Is this entrypoint downstream from another trusted proxy?
> No, clients dial directly to this server. (Turn off Proxy Protocol)
  Yes, clients are proxied through another trusted proxy. (Turn on Proxoy Protocol)

Do not enable Proxy Protocol

SSH does not support Proxy Protocol, so be sure to disable it.

Press ESC four times to quit the config tool.

Create a route from the forgejo entrytpoint to the Pi

Run this on your Raspberry Pi

sentry route set pi forgejo \
  --layer4 --proxy-protocol false

Tip

You may also create the route interactively through the Traefik config menu.

Test cloning a repository via SSH

Login to your Forgejo instance
Create a new repository
On the repository page, click on SSH and copy the SSH URL.

[bash]: Run this on your workstation:

git clone ssh://git@git.pi.example.com:2222/username/repository.git