Skip to content

Forgejo

Forgejo is a self-hosted Git service with a functionality similar to GitHub, GitLab and BitBucket. It's a hard-fork of Gitea, created in 2022. Forgejo changed its license in August 2024 from MIT (inherited from Gitea) to the GNU General Public licence. Like most applications written in Go it’s easy to install.

This guide installs the application at ~/opt/forgejo/. The service is named “forgejo”, uses port 3000 internally and is exposed at git.example.com. It logs to the systemd journal.

Website
Forgejo
License
GPLv3
Author
Oliver Hanraths
Last changed
2026-10-03

Tested with Forgejo 16.0.5 on Uberspace 8.0.97. We can't guarantee it to work with newer versions.

Report a guide issue

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites

Example output below is abbreviated. Commands shown without output produce no output on success.

You'll need your MariaDB credentials:

[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword

Installation

Application

Download latest version in the linux-amd64 variant into ~/opt/forgejo/:

[isabell@moondust ~]$ mkdir -p ~/opt/forgejo
[isabell@moondust ~]$ cd ~/opt/forgejo
[isabell@moondust ~]$ latest=$(curl -s 'https://forgejo.org/releases/rss.xml' | grep -oP '<title>\Kv[0-9]+\.[0-9]+\.[0-9]+(?=</title>)' | head -n 1 | sed 's/^v//')
[isabell@moondust ~]$ wget https://codeberg.org/forgejo/forgejo/releases/download/v${latest}/forgejo-${latest}-linux-amd64.xz
…
Saving to: ‘forgejo-16.0.5-linux-amd64.xz’
…

Download and verify the PGP signature:

[isabell@moondust ~]$ wget https://codeberg.org/forgejo/forgejo/releases/download/v${latest}/forgejo-${latest}-linux-amd64.xz.asc
…
Saving to: ‘forgejo-16.0.5-linux-amd64.xz.asc’
…
[isabell@moondust ~]$ gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
…
gpg: key A4B61A2DC5923710: public key "Forgejo <contact@forgejo.org>" imported
[isabell@moondust ~]$ gpg --verify forgejo-${latest}-linux-amd64.xz.asc
…
gpg: Good signature from "Forgejo <contact@forgejo.org>" [unknown]
[isabell@moondust ~]$ rm forgejo-${latest}-linux-amd64.xz.asc

Extract the binary, make it executable and create a symbolic link to ~/opt/forgejo/forgejo without version suffix:

[isabell@moondust ~]$ unxz forgejo-${latest}-linux-amd64.xz
[isabell@moondust ~]$ chmod u+x forgejo-${latest}-linux-amd64
[isabell@moondust ~]$ ln --force --symbolic forgejo-${latest}-linux-amd64 forgejo

Service

Create a systemd service unit at ~/.config/systemd/user/forgejo.service with the following content:

[Unit]
Description=Forgejo

[Install]
WantedBy=default.target

[Service]
WorkingDirectory=%h/opt/forgejo
ExecStart=%h/opt/forgejo/forgejo web

Web Access

Add a domain and create a web backend to make the service available:

[isabell@moondust ~]$ uberspace web domain add git.example.com
OK: Added domain 'git.example.com' to your Asteroid
[isabell@moondust ~]$ uberspace web backend add git.example.com port 3000
OK: Added webbackend 'git.example.com/' to your Asteroid

Info

Do not forget to add the DNS entries!

Database

[isabell@moondust ~]$ mariadb -e "CREATE DATABASE ${USER}_forgejo CHARACTER SET utf8mb4 COLLATE utf8mb4_bin"

Configuration

We will need to create some random characters as a security key for the configuration:

[isabell@moondust ~]$ ~/opt/forgejo/forgejo generate secret SECRET_KEY
<RANDOM_64_CHARACTERS_FROM_GENERATOR>

Copy or save the output for later.

Configuration File

Create a custom directory for your configurations:

[isabell@moondust ~]$ mkdir --parents ~/opt/forgejo/custom/conf/
[isabell@moondust ~]$ touch ~/opt/forgejo/custom/conf/app.ini
[isabell@moondust ~]$ chmod 600 ~/opt/forgejo/custom/conf/app.ini

Create a config file ~/opt/forgejo/custom/conf/app.ini with the following content:

Note

  • Replace isabell with your username
  • Replace git.example.com with your domain
  • Fill the database password PASSWD = with yours
  • Enter the generated random into SECRET_KEY =
[server]
DOMAIN = git.example.com
ROOT_URL = https://git.example.com
OFFLINE_MODE = true ; privacy option.
LFS_START_SERVER = true ; Enables Git LFS support
SSH_ALLOW_UNEXPECTED_AUTHORIZED_KEYS = true ; Keep Uberspace login keys in authorized_keys

[database]
DB_TYPE  = mysql
HOST     = 0.0.0.0:3306
NAME     = isabell_forgejo
USER     = isabell
PASSWD   = <MariaDB_PASSWORD>

[security]
INSTALL_LOCK        = true
MIN_PASSWORD_LENGTH = 8
PASSWORD_COMPLEXITY = lower ; This allows well to remember but still secure passwords
SECRET_KEY          = <RANDOM_64_CHARACTERS_FROM_GENERATOR> ; the before generated security key

[service]
DISABLE_REGISTRATION       = true ; security option, only admins can create new users.
SHOW_REGISTRATION_BUTTON   = false
REGISTER_EMAIL_CONFIRM     = true
DEFAULT_ORG_VISIBILITY     = private ; [public, limited, private]
DEFAULT_KEEP_EMAIL_PRIVATE = true
NO_REPLY_ADDRESS           = noreply.isabell.uber.space

[mailer]
ENABLED     = true
PROTOCOL    = sendmail ; [smtp, smtps, smtp+starttls, smtp+unix, sendmail, dummy]
FROM        = isabell@uber.space

Note

This config block contains a secure and convenient basic configuration. You may change it depending on your needs and knowledge. See the Forgejo documentation and configuration sample for more configuration possibilities. SSH_ALLOW_UNEXPECTED_AUTHORIZED_KEYS is needed because Forgejo shares the Uberspace account with your regular SSH login keys; otherwise it refuses to start.

Database Initialization

Migrate the database configurations:

[isabell@moondust ~]$ ~/opt/forgejo/forgejo migrate
…
… [I] PING DATABASE mysql

Admin user

Set your admin login credentials:

[isabell@moondust ~]$ ADMIN_USERNAME='admin_user'
[isabell@moondust ~]$ ADMIN_PASSWORD='change_me!'
[isabell@moondust ~]$ ~/opt/forgejo/forgejo admin user create --username "${ADMIN_USERNAME}" --password "${ADMIN_PASSWORD}" --email "${USER}@uber.space" --admin
New user 'admin_user' has been successfully created!

Note

Forgejo does not allow “admin” as name, of course you should choose and replace the password!

SSH Setup

After starting the service below, users can add their SSH keys via the menu in the upper right corner → Settings → SSH/GPG Keys → Add Key. Forgejo automatically writes an SSH key command for each added SSH key into the $HOME/.ssh/authorized_keys file, allowing Git access to the instance.

Warning

Use different SSH keys for your Uberspace shell login and Forgejo. Keep your Uberspace login key in the Uberspace dashboard and add only the separate Git key to Forgejo. Do not replace your login key with a Forgejo command in authorized_keys, as that removes shell access through that key.

Configure your local SSH client to select the Forgejo key for Git connections, for example with an IdentityFile and IdentitiesOnly yes entry for git.example.com in ~/.ssh/config.

Start Service

Reload systemd, enable the service for automatic startup, and start it now:

[isabell@moondust ~]$ systemctl --user daemon-reload
[isabell@moondust ~]$ systemctl --user enable --now forgejo
Created symlink '/home/isabell/.config/systemd/user/default.target.wants/forgejo.service' → '/home/isabell/.config/systemd/user/forgejo.service'.
[isabell@moondust ~]$ systemctl --user status forgejo
● forgejo.service - Forgejo
     Loaded: loaded (/home/isabell/.config/systemd/user/forgejo.service; enabled; preset: enabled)
     Active: active (running)
…

Startup can take about a minute while Forgejo checks its database. Once it is ready, open https://git.example.com and log in with the admin credentials.

Maintenance

Backup

The Forgejo CLI (command line interface) has a built-in backup command to create a zip file with the database, repos, config, log, data. Stop the service while backing up so these stay consistent:

[isabell@moondust ~]$ mkdir --parents ~/backups ~/opt/forgejo/data/forgejo-repositories
[isabell@moondust ~]$ systemctl --user stop forgejo
[isabell@moondust ~]$ ~/opt/forgejo/forgejo dump --file ~/backups/forgejo-dump.zip --skip-repo-archives
…
… [I] Finished dumping in file /home/isabell/backups/forgejo-dump.zip
[isabell@moondust ~]$ mariadb-dump --single-transaction "${USER}_forgejo" > ~/backups/forgejo-db.sql

Creating the repository directory also allows backups before you have created your first repository. Keep the separate MariaDB dump: Forgejo documents restore problems with its built-in SQL dump. The commands overwrite previous backups at these paths; copy them elsewhere if you need to retain them. Unless you are updating, start the service again:

[isabell@moondust ~]$ systemctl --user start forgejo

For restoring, see the Gitea restore instructions. Adapt the paths to ~/opt/forgejo/, use the forgejo binary and service, and restore the separate MariaDB dump.

Updates

Note

Check the release feed regularly to stay informed about the newest version.

  1. Read the upgrade notes and create a backup, leaving the service stopped.
  2. Repeat the Application steps to download and verify the new version, set its permissions and update the symbolic link.
  3. Check if you have to modify the config file (see the configuration sample).
  4. Run the database migration, then start the service and check that the web interface and your repositories work.