Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Forgejo Self-Hosting

Forgejo is a self-hosted git service. Think of it as GitHub or Codeberg, a platform on which you can store your git repositories, make commits, pushes, clones etc. Forgejo provides you with ability to host your own git repositories on a server.

I wanted to do it for some time although I don’t have many repositories. I have my server setup on UpCloud which is an EU cloud service provider based in Helsinki. They have their data centers all over Europe, nice web interface and reasonable pricing. My own setup is a 2 cores CPU, 8GB RAM and 40GB disk storage running Debian 13. It is pretty light-weight. I have firewall and nginx configured there and I host this Knowledge Base there as well as my website.

Let’s now setup our Forgejo instance on the server and migrate a couple of repositories there.

Forgejo Setup

Prepare a Subdomain

I use Porkbun for my domain management. To create a new subdomain, go to your domain DNS records and add an A record with git as subdomain host and pointing to the IP of your VPS.

After that you need to get a certificate for your new subdomain so that you can have an HTTPS connection. Log in to your server via SSH, then do:

sudo certbot --nginx -d git.yourdomain.com

This will run the process of getting you a new certificate.

Installing Forgejo

You are now ready to install Forgejo. There are a few options available. I don’t want to mess with Docker so I will install Forgejo binary on my VPS. Lookup the latest release binary on Frogejo git repository. Then in your VPS do the following:

wget -O forgejo https://codeberg.org/forgejo/forgejo/releases/download/<version-number>/forgejo-<version>-<architecture>
chmod +x forgejo
sudo mv forgejo /usr/local/bin/forgejo

wget -O will download the binary and save it under name forgejo. Then you make it executable and move it to where you naturally store system-wide binaries on Linux.

Creating Dedicated User

As always it is a good practice to create a separate user to manage services such as git. I already have git user on my VPS because I am managing bare git repositories with it. Instead of using that user, I will create a dedicated forgejo user.

sudo adduser --system --group --disabled-password --home /home/forgejo forgejo
sudo mkdir -p /var/lib/forgejo /etc/forgejo
sudo chown forgejo:forgejo /var/lib/forgejo

/var/lib/forgejo directory is where our git repositories, logs and all other forgejo stuff will live. /etc/forgejo will contain app.ini configuration file. It is critical to make sure that forgejo user owns those directories!

Setting Up systemd Service

To make sure that forgejo is always running on our VPS, we need to setup a systemd service for it. Let’s create /etc/systemd/system/forgejo.service which will contain service configuration:

[Unit]
Description=Forgejo
After=network.target

[Service]
User=forgejo
Group=forgejo
WorkingDirectory=/var/lib/forgejo
ExecStart=/usr/local/bin/forgejo web --config /etc/forgejo/app.ini
Restart=always
Environment=USER=forgejo HOME=/home/forgejo FORGEJO_WORK_DIR=/var/lib/forgejo

[Install]
WantedBy=multi-user.target

Side Note: This is the final version services file but be prepared to troubleshoot if forgejo web interface will not be able to find certain configuration directories. The variable FORGEJO_WORK_DIR=/var/lib/forgejo is what I eventually needed to add for everything to work. Generally, though to troubleshoot any issues use this as a guidance:

  • check folders permissions for key forgejo errors
  • check service logs with journalctl -u forgejo -n 50 --no-pager
  • check /etc/forgejo/app.ini for any missing configuration

Create nginx Reverse Proxy

Now it is time to setup nginx to direct requests to our git.yourdomain.com server via localhost on port 3000 that is the port that forgejo uses by default. Create a file /etc/nginx/sites-available/forgejo with the following content:

server {
    server_name git.yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Now reload nginx to pick up the newly added site:

sudo ln -s /etc/nginx/sites-available/forgejo /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

This should return no errors. Your forgejo instance should now be ready to go however…

SSH

I manage my VPS with SSH remote access. Naturally, port 22 is occupied for this. By default forgejo also wants to bind to port 22 which will conflict with how I work now. In order to avoid that we will make forgejo use port 2222 instead. But before we do that we need to take care of firewall.

Firewall Config

The way it works on UpCloud, is that they have their own network firwall which you can configure + you can configure your own rules on your VPS. My rules are simple, allow incoming traffic on ports 22, 80, 443, basic stuff. Now we need to add port 2222 to that so that our forgejo instance could accept requests.

sudo ufw status verbose # check which rules you already have
# Then do
sudo ufw allow 2222/tcp # allow incoming traffic on port 2222
sudo ufw status verbose # confirm that rule is set

In UpCloud network firewall I have configured the firewall the same way.

At this point you should be ready to run forgejo setup wizard.

Forgejo Setup Wizard

First, make sure that your forgejo service is running. So do this:

sudo systemctl enable forgejo --now
sudo systemctl start forgejo
sudo systemctl status forgejo

This should return a green active status. Now open git.yourdomain.com in your browser which should open a Forgejo configuration page. It should pick up all the directories correctly from your systemd configuration. If it does not, then you will need to find the reason for that (see above for troubleshooting guidance). Hopefully, all configuration directories are picked up. All you need to do now is to:

  • select database that you want to use. I use sqlite as it is more than enough for me but mysql and postgres are alsow available.
  • change SSH port from 22 to 2222.
  • below on the page expand Administration section and configure your admin account. This will allow you to login to your forgejo.

After all that just click Install Forgejo. This will take you to final Forgejo interface which looks a lot like Codeberg. You will be singed in already so now you can work on creating new repositories and all that good stuff.

Testing Forgejo Instance

To test that everything is working first just hit forgejo with this:

ssh -p 2222 forgejo@git.yourdomain.com

You want get a shell but something like Permission Denied should appear which means that we can reach out to our forgejo instance. You can also create a test repository on git.yourdomain.com and you should be able to clone it via HTTPS. We need to configure our SSH client so that it we can also do everything via ssh.

ssh-keygen -t ed25519 -a 100 # generates a new key

I try to use different keys for different services so I rename the default key file name to id_ed25519_forgejo. No that key is generated we need to copy it and put into forgejo.

xclip -selection clipboard < ~/.ssh/id_ed25519_forgejo.pub

Now go to git.yourdomain.com -> Settings -> SSH and GPG and click on Add key in SSH section. Paste your copied key into the text field and save. Then also click on Verify and follow the instructions that will appear on the screen. After this you should be ready to setup your local SSH client. Forgejo has a good guide on how to configure your SSH keys. Now on your local machine you need to explain your SSH client what is forgejo and how to connect to it. Since I use a custom name for a key file I will add the following to my ~/.ssh/config:

Host git.nikolaydudaev.com
    HostName git.yourdomain.com
    Port 2222
    User forgejo
    IdentityFile ~/.ssh/id_ed25519_forgejo

Now you should be ready to do all the cloning and pushing that you want via ssh. Simple flow is:

  • create new repository on git.yourdomain.com. It will show you instructions how to connect to your local repository.
  • generally, even if you have other remotes configured you can always add another one with git remote add forgejo <repo URL>

And voila! You are now hosting your own git repositories on the VPS that you are managing yourself! Congratulations!

Conclusion

There were some hickups along the way while I was doing this. They were related to the configuration directories that Forgejo installation wizard could not find or did not have proper permissions for. But eventually, after some troubleshooting, everything worked smooth and nice. I am very excited about this now as I think more and more about Digital Autonomy these days!