Forgejo is a self-hosted Git service with a functionality similar to GitHub, GitLab and BitBucket. It’s a soft-fork of Gitea and uses the same MIT licence. As most applications written in Go it’s easy to install.


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


You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
[isabell@stardust ~]$

We need a database:

[isabell@stardust ~]$ mysql --execute "CREATE DATABASE ${USER}_forgejo"
[isabell@stardust ~]$

We can use the uberspace or your own domain:

[isabell@stardust ~]$ uberspace web domain list
[isabell@stardust ~]$



Check current version of Forgejo at releases page:

[isabell@stardust ~]$ mkdir ~/forgejo
[isabell@stardust ~]$ wget -O ~/forgejo/forgejo-1.21.3-0
Saving to: ‘/home/isabell/forgejo/forgejo-1.21.3-0’

100%[=======================================================>] 105,054,768 27.9MB/s   in 3.9s

2023-12-28 22:22:22 (26.0 MB/s) - ‘forgej0-1.21.3-0’ saved [105054768/105054768]

[isabell@stardust ~]$

Set permissions

Make the downloaded binary executable:

[isabell@stardust ~]$ chmod u+x ~/forgejo/forgejo-1.21.3-0
[isabell@stardust ~]$ ln -fs ~/forgejo/forgejo-1.21.3-0 ~/forgejo/forgejo
[isabell@stardust ~]$


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

[isabell@stardust ~]$ ~/forgejo/forgejo generate secret SECRET_KEY
[isabell@stardust ~]$

Copy or save the output for later.

Forgejo configuration file

Create a custom directory for your configurations:

[isabell@stardust ~]$ mkdir --parents ~/forgejo/custom/conf/
[isabell@stardust ~]$

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


Replace isabell with your username, fill the database password PASSWD = with yours and enter the generated random into SECRET_KEY =.

DOMAIN               =
ROOT_URL             = https://%(DOMAIN)s
OFFLINE_MODE         = true ; privacy option.
LFS_START_SERVER     = true ; Enables Git LFS support

DB_TYPE  = mysql
NAME     = isabell_forgejo
USER     = isabell

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

DISABLE_REGISTRATION       = true ; security option, only admins can create new users.
DEFAULT_ORG_VISIBILITY     = private ; [public, limited, private]
NO_REPLY_ADDRESS           =

ENABLED     = true
PROTOCOL    = sendmail ; [smtp, smtps, smtp+starttls, smtp+unix, sendmail, dummy]
FROM        =


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 the Forgejo configuration sample for more configuration possibilities.

Database initialization

Migrate the database configurations:

[isabell@stardust ~]$ ~/forgejo/forgejo migrate
2023/12/28 22:23:23 models/db/engine.go:126:SyncAllTables() [I] [SQL] CREATE INDEX `IDX_package_version_created_unix` ON `package_version` (`created_unix`) [] - 25.0114ms
2023/12/28 22:23:23 models/db/engine.go:126:SyncAllTables() [I] [SQL] CREATE INDEX `IDX_package_version_is_internal` ON `package_version` (`is_internal`) [] - 29.933338ms
[isabell@stardust ~]$

Forgejo admin user

Set your admin login credentials:

[isabell@stardust ~]$ ADMIN_USERNAME=AdminUsername
[isabell@stardust ~]$ ADMIN_PASSWORD='SuperSecretAdminPassword'
[isabell@stardust ~]$ ~/forgejo/forgejo admin user create --username ${ADMIN_USERNAME} --password ${ADMIN_PASSWORD} --email ${USER} --admin
New user 'AdminUsername' has been successfully created!
[isabell@stardust ~]$


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

Finishing installation

Service for Forgejo

To keep Forgejo up and running in the background, you need to create a service that takes care for it. Create a config file ~/etc/services.d/forgejo.ini for the service:

command=%(ENV_HOME)s/forgejo/forgejo web

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$


The status of forgejo must be RUNNING. If its not check the log output at ~/logs/supervisord.log and the configuration file ~/forgejo/custom/conf/app.ini.

Uberspace web backend


forgejo is running on port 3000.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Done. We can point our browser to

Installed files and folders are:

  • ~/forgejo/

  • ~/etc/services.d/forgejo.ini


The Forgejo CLI (command line interface) has a build-in backup command to create a full backup in a zip file with the database, repos, config, log, data


To restore a backup follow the backup and restore documentation

Execute the following command:

[isabell@stardust ~]$ ~/forgejo/forgejo dump
2023/12/28 22:23:23 ...les/setting/cache.go:75:loadCacheFrom() [I] Cache Service Enabled
2023/12/28 23:23:23 cmd/dump.go:265:runDump() [I] Dumping local repositories... /home/kyber/forgejo/data/forgejo-repositories
2023/12/28 23:23:23 cmd/dump.go:306:runDump() [I] Dumping database...
2023/12/28 23:23:24 cmd/dump.go:430:runDump() [I] Finish dumping in file
[isabell@stardust ~]$



Check the update feed or releases page regularly to stay informed about the newest version.

Manual updating

  • Do the Download and Set permissions steps from above.

  • Check if you have to modify the config file. (See documentation and the file sample.)

  • Do the database migration: ~/forgejo/forgejo migrate

  • Start the application supervisorctl restart forgejo

  • Check if the application is running supervisorctl status forgejo

Additional configuration

Forgejo ssh setup (optional)

Forgejo can manage the ssh keys. To use this feature we have to link the ssh folder into the forgejo folder.

[isabell@stardust ~]$ ln -s ~/.ssh ~/forgejo/.ssh
[isabell@stardust ~]$

Now our Forgejo users can add their ssh keys via the menu in the up right corner: -> settings -> tab: SSH/GPG Keys -> Add Key. Forgejo is automatically writing a ssh key command into the /home/isabell/.ssh/authorized_keys file. The key line is something similar like:

command="/home/isabell/forgejo/forgejo --config='/home/isabell/forgejo/custom/conf/app.ini' serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAAC... youruser@yourhost

If we’re using the same ssh key for auth to Uberspace and Forgejo, we need to modify the server /home/isabell/.ssh/authorized_keys file.

command="if [ -t 0 ]; then bash; elif [[ ${SSH_ORIGINAL_COMMAND} =~ ^(scp|rsync|mysqldump).* ]]; then eval ${SSH_ORIGINAL_COMMAND}; else /home/isabell/forgejo/forgejo serv key-1 --config='/home/isabell/forgejo/custom/conf/app.ini'; fi",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-...


  • Be careful to keep the key number key-X, keep your key ssh-... and change the username isabell to yours.

  • Take care that there is no second line propagating the same ssh key.


You can still use the Uberspace dashboard to add other ssh keys for running default ssh sessions.

To interact with Forgejo at our local machine like git clone we configure the /home/localuser/.ssh/config file for our local machine with the git ssh key.

    User isabell
    IdentityFile ~/.ssh/id_your_git_key
    IdentitiesOnly yes

Forgejo using external renderer (optional)

Forgejo supports custom file renderings (i.e. Jupyter notebooks, asciidoc, etc.) through external binaries to provide a preview.
In this case we install an external rendering extension for AsciiDoc.
AsciiDoctors location will be here: ~/.gem/ruby/3.2.0/*/asciidoctor*
[isabell@stardust ~]$ gem install asciidoctor
Fetching asciidoctor-2.0.20.gem
WARNING:  You don't have /home/isabell/.gem/ruby/3.2.0/bin in your PATH,
        gem executables will not run.
Successfully installed asciidoctor-2.0.20
1 gem installed
[isabell@stardust ~]$


Don’t be irritated by the warning that the bin folder isn’t in the path. Uberspace is taking care of it. You can check with [isabell@stardust ~]$ which asciidoctor.

Now we have to append the config file ~/forgejo/custom/conf/app.ini with:

ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -e -a leveloffset=-1 --out-file=- -"

Tested with Forgejo 1.21.3-0, Uberspace 7.15.8

Written by: Marc Redwerkz <>