Self-host Forgejo on a VPS

To self-host Forgejo on a VPS, install its signed release binary as a service running as a git user, keep its web interface on localhost behind a reverse proxy with HTTPS, and let Git over SSH use the server's own SSH. On VPSNine the Forgejo one-click app does that from the long-term-support line, with registration off and an owner account only you know.

Forgejo is a fork of Gitea run by the community, with repositories, issues, pull requests, packages and Actions. It's a single Go program, so it's light on a small server.

What you need#

• The Budget plan runs Forgejo for one person or a small team, with SQLite. Choose Standard for large repositories, many users, or a Forgejo Actions runner on the same server; CI jobs are what use the CPU. The plans page has the specs.
• A domain or subdomain, like git.example.com.
• An SSH key on your computer for pushing. SSH keys explains how to make one.

Forgejo Actions needs a separate Forgejo Runner, which the one-click app doesn't install.

Install it with the one-click app#

Order a server with the Forgejo app. It downloads the newest v15 LTS binary from Codeberg, checks its signature, and sets it up as Forgejo's binary-install guide describes: a git user, SQLite in /var/lib/forgejo, the configuration in /etc/forgejo/app.ini, the web interface on 127.0.0.1:3000 and Git over the server's own SSH on port 22. The install page is locked, registration is off, and the owner account is made from the command line with a random password.

1. Log in over SSH and read the owner account's password:

   bash

   cat /root/forgejo-admin.txt

2. From your computer, open a tunnel to the web interface:

   bash

   ssh -L 3000:127.0.0.1:3000 root@203.0.113.10

   Open http://localhost:3000, log in as owner, and set your real email in Settings.

3. Set up HTTPS (next section).

4. Add your SSH public key in Settings, SSH / GPG keys, create a repository, then push:

   bash

   git remote add origin git@git.example.com:owner/myproject.git
   git push -u origin main

On the server, curl http://127.0.0.1:3000/api/healthz reports pass when Forgejo is healthy.

Put it on your domain with HTTPS#

Nothing is public until you do this. Point an A record for git.example.com at the server, allow ports 80 and 443 in the panel firewall, then run:

vps9-https git.example.com

First it sets DOMAIN, ROOT_URL (https://git.example.com/) and SSH_DOMAIN in /etc/forgejo/app.ini and restarts Forgejo, so the clone addresses it shows are right. Then it installs Caddy, which proxies the domain to 127.0.0.1:3000 and gets and renews the certificate. Run it again with another domain to move.

Port 22 is already open for SSH, and Git uses it too, so there's nothing else to open.

Doing it by hand on another server#

Follow Forgejo's binary installation guide. In outline:

1. Download the binary for your architecture from Forgejo's releases on Codeberg, check its GPG signature as the download page describes, and install it as /usr/local/bin/forgejo with mode 755.
2. Install git and git-lfs, and create a git system user with /home/git as its home.
3. Create /var/lib/forgejo (owned by git, mode 750) and /etc/forgejo (owned by root:git).
4. Install the systemd unit from Forgejo's repository as /etc/systemd/system/forgejo.service, then systemctl enable --now forgejo.
5. Finish the web installer on port 3000. Reach it through an SSH tunnel rather than opening 3000 to the internet, set the base URL to your https:// domain, and create the admin account there.
6. Tighten /etc/forgejo to mode 750 and app.ini to 640 afterwards, and put Caddy or nginx in front for HTTPS.

Updates and backups#

Updates are yours to run. Read the release notes, download the next v15 binary from Codeberg, and check its signature against Forgejo's release key:

gpg --keyserver hkps://keys.openpgp.org --recv-keys EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
gpg --verify forgejo-15.x.y-linux-amd64.asc forgejo-15.x.y-linux-amd64

Then replace the binary and restart:

install -m 0755 forgejo-15.x.y-linux-amd64 /usr/local/bin/forgejo
systemctl restart forgejo

v15 is supported until July 2027. The one-click app turns on the operating system's automatic security updates, which don't touch Forgejo.

Back up with forgejo dump, run as the git user from a folder it can write to:

cd /home/git
runuser -u git -- env HOME=/home/git forgejo dump -c /etc/forgejo/app.ini -w /var/lib/forgejo

It writes a zip archive of the repositories, database and configuration to the current folder. Copy it off the server; Backups you should run shows how to schedule it.

When it goes wrong#

• git clone or git push over SSH says Permission denied (publickey): Git over SSH logs in as the git user, never as root or your own name, and only accepts the keys you added in Forgejo under Settings, SSH / GPG keys. Use git@git.example.com:owner/repo.git and check the key you added is the one your computer offers (ssh -T git@git.example.com tells you who Forgejo thinks you are).
• Clone addresses show the server's IP address or localhost: vps9-https hasn't run yet, so DOMAIN and SSH_DOMAIN still hold the defaults. Run it with your domain.
• You moved the server's SSH to another port: Git follows it. Set SSH_PORT in /etc/forgejo/app.ini to the new port, run systemctl restart forgejo, and allow that port in the panel firewall.