Forgejo

Forgejo is an open source git forge that aims to implement federation using the ActivityPub protocol. It can be self-hosted to provide code collaboration services similar to GitHub, such as remote git repositories, issue tracking, and pull/merge requests.

Step 0 (Optional): Change your SSH to a nonstandard port

Git forges provide the ability to interact via HTTP or SSH. If you want users to interact with your Forgejo instance using the standard SSH port, and you have an existing SSH server on the same device, you must move your regular SSH server to another port. Forgejo supports SSH over other ports, but all of your users will have to specify that port in their git clone commands or configure it in their ~/.ssh/ssh_config file.

To change your SSH port, edit /etc/ssh/sshd_config, uncomment the line starting with Port, and change the number to something other than 22. Open the corresponding port in your firewall. For more information on firewall configuration, see Firewalling Basics.

Step 1: Install Forgejo

Go to the delightful forgejo repository and check whether Forgejo has been packaged for your operating system or distribution. If so, install using your package manager. Otherwise, go to the Forgejo installation page, decide whether you're going to install from binary or from a docker container, and follow the corresponding instructions. Make sure you complete initial setup before moving to the next step.

Step 2: Open Forgejo ports in your device firewall

If you installed using Docker or Docker Compose, and want to use nonstandard ports, change the Docker port mappings. You will not need to open the ports in your firewall, because Docker port mappings are done via an iptables chain that takes precedence over user-configured rules. This means ports mapped using Docker will be immediately publicly accessible once you enable your 44Net Connect tunnel, so don't enable it until you've completed initial setup.

If you installed Forgejo from a binary, the ports used for the web UI are not editable from the web UI. Instead, edit the config file at /etc/forgejo/app.ini, and change the HTTP_PORT and SSH_PORT lines. Then, open the corresponding ports in your firewall. The default ports are 3000 for the web UI, and 222 for SSH. For more information on firewall configuration, see Firewalling Basics.

Note that you cannot put the web UI on the same port as Forgejo's SSH access.

Step 3: Set up 44Net Connect tunnel

Set up a single device tunnel on the machine that will host your Forgejo instance. Go to the list of single device tunnel tutorials and follow the one for your operating system.

Step 4: Validate Forgejo functionality

Make sure your Forgejo instance is working by testing a few operations.

Create a repository using the web UI

Log into Forgejo and go to the Forgejo home page. Click the plus button at the top right, and click "New Repository." Fill in the details (specifics don't matter, since this is a test), and if the repository is successfully created, move on to the next step.

Clone the repository over HTTP

Copy the HTTP URL from Forgejo, go to your terminal, and run git clone <URL>. It should go through "Enumerating objects," "Counting objects," and "Compressing objects" before finishing.

If the clone completes without error, delete the folder and move on to cloning via SSH. If you get some error such as "Repository not found" or similar, you may have a configuration issue, and should proceed to the troubleshooting section.

Clone the repository over SSH

Copy the SSH URL from Forgejo, go to your terminal, and run git clone <URL>. Just like before, it should go through "Enumerating objects," "Counting objects," and "Compressing objects" before finishing.

If the clone completes without error, delete the folder and move on to cloning via SSH. If you get some error such as "Repository not found" or "Permission denied: pubkey," you may have a configuration issue, and should proceed to the troubleshooting section.

Make a commit and push it to the remote repository

After cloning the repository, make a commit and push it to the remote repository with the following steps:

Create or modify a file in the repository's folder
Add your changes with git add <file>
Commit your changes with git commit -m <message>
Push to the remote repository with git push

The push command should proceed through enumerating objects, counting objects, delta compression, compressing objects, and writing objects, then finish. If it throws an error (any line starting with fatal), then you may have a configuration issue and should consult the troubleshooting section. If these are all working, you should be good to go!

Troubleshooting

Can't connect to Forgejo web UI

Make sure you're accessing the correct port. Unless you specify the port, your browser will default to port 80 for HTTP or port 443 for HTTPS. The default port for the web UI is 3000.
Use systemctl status <name of unit> to make sure your 44Net Connect tunnel is up. The name of the tunnel's systemd unit should be wg-quick@<name of config file>.
If you're using Docker, make sure your port mappings are correct. Those can be viewed by running sudo docker ps -a to list all containers. Containers created using Docker compose can have their port mappings viewed in their compose file.
If you're not using Docker, ensure your device firewall has the correct ports open. firewall-cmd users should also make sure their 44Net Connect WireGuard interface is in the correct zone.

Can't clone repository over SSH

Forgejo does not operate on the same SSH port as your system's sshd server. The default port for Forgejo SSH is 222. Unless you change this to 22 (and move your sshd port somewhere else), you'll have to specify the correct port when cloning the repository. For example, git clone ssh://git@yoursite.org:<port here>/username/repository.

If you're getting Permission denied (publickey), you may be attempting to SSH into the sshd port rather than the Forgejo port.