Forgejo — UberLab 7 documentation

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 it’s license in August 2024 from MIT (inherited from Gitea) to the GNU GPL v2 licence. Like most applications written in Go it’s easy to install.

Prerequisites

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

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

We need a database:

[isabell@stardust ~]$ mysql --execute "CREATE DATABASE ${USER}_forgejo CHARACTER SET utf8mb4 COLLATE utf8mb4_bin"
[isabell@stardust ~]$

We can use the uberspace or your own domain:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation

Download

Check current version of Forgejo at releases page or scrape it from feed with this one liner:

[isabell@stardust ~]$ FORGEJO_HOME="$HOME/forgejo"
[isabell@stardust ~]$ mkdir $FORGEJO_HOME
[isabell@stardust ~]$ feed_url='https://forgejo.org/releases/rss.xml'
[isabell@stardust ~]$ latest=$(curl -s "$feed_url" | grep -oP '<title>\Kv[0-9]+\.[0-9]+\.[0-9]+(?=</title>)' | head -n 1 | sed 's/^v//')
[isabell@stardust ~]$ wget -c -P /tmp https://codeberg.org/forgejo/forgejo/releases/download/v${latest}/forgejo-${latest}-linux-amd64.xz
[...]
Saving to: ‘/tmp/forgejo-9.0.3-linux-amd64.xz’

100%[=======================================================>] 33,034,888  62.1MB/s   in 0.5s

2024-12-27 17:08:07 (62.1 MB/s) - ‘/tmp/forgejo-9.0.3-linux-amd64.xz’ saved [33034888/33034888]

[isabell@stardust ~]$

Set permissions

Make the binary executable:

[isabell@stardust ~]$ chmod u+x $FORGEJO_HOME/forgejo-${latest}
[isabell@stardust ~]$ ln --force --symbolic $FORGEJO_HOME/forgejo-${latest} $FORGEJO_HOME/forgejo
[isabell@stardust ~]$

Configuration

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

[isabell@stardust ~]$ $FORGEJO_HOME/forgejo generate secret SECRET_KEY
<RANDOM_64_CHARACTERS_FROM_GENERATOR>
[isabell@stardust ~]$

Copy or save the output for later.

Forgejo configuration file

Create a custom directory for your configurations:

[isabell@stardust ~]$ mkdir --parents $FORGEJO_HOME/custom/conf/
[isabell@stardust ~]$ touch $FORGEJO_HOME/custom/conf/app.ini
[isabell@stardust ~]$

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

Note

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

[server]
DOMAIN               = isabell.uber.space
ROOT_URL             = https://%(DOMAIN)s
OFFLINE_MODE         = true ; privacy option.
LFS_START_SERVER     = true ; Enables Git LFS support

[database]
DB_TYPE  = mysql
HOST     = 127.0.0.1:3306
NAME     = isabell_forgejo
USER     = isabell
PASSWD   = <MySQL_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 the Forgejo configuration sample for more configuration possibilities.

Database initialization

Migrate the database configurations:

[isabell@stardust ~]$ $FORGEJO_HOME/forgejo migrate
2024/12/27 17:17:48 cmd/migrate.go:33:runMigrate() [I] AppPath: /home/isabell/forgejo/forgejo
2024/12/27 17:17:48 cmd/migrate.go:34:runMigrate() [I] AppWorkPath: /home/isabell/forgejo
2024/12/27 17:17:48 cmd/migrate.go:35:runMigrate() [I] Custom path: /home/isabell/forgejo/custom
2024/12/27 17:17:48 cmd/migrate.go:36:runMigrate() [I] Log path: /home/isabell/forgejo/log
2024/12/27 17:17:48 cmd/migrate.go:37:runMigrate() [I] Configuration file: /home/isabell/forgejo/custom/conf/app.ini
2024/12/27 17:17:48 ...2@v2.27.4/command.go:269:Run() [I] PING DATABASE mysql
[isabell@stardust ~]$

Forgejo admin user

Set your admin login credentials:

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

Note

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

Finishing installation

Service for Forgejo

[isabell@stardust ~]$ touch $HOME/etc/services.d/forgejo.ini
[isabell@stardust ~]$

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

[program:forgejo]
directory=%(ENV_HOME)s/forgejo
command=%(ENV_HOME)s/forgejo/forgejo web
startsecs=30
autorestart=yes

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 ~]$

Note

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

Uberspace web backend

Note

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 https://isabell.uber.space/.

Installed files and folders are:

$FORGEJO_HOME
$HOME/etc/services.d/forgejo.ini

Forgejo SSH setup

In order for users to be able to push to your Forgejo instance, they need to 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. The key line is something similar like:

command="$FORGEJO_HOME/forgejo --config=$FORGEJO_HOME/custom/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty,no-user-rc,restrict ssh-ed25519 AAAAC... user@host

Warning

If you’re using the same SSH key for authentication to Uberspace and Forgejo, you need to modify the server $HOME/.ssh/authorized_keys file. Otherwise, you’ll lock yourself out from accessing your Uberspace via SSH. An alternative approach would be to add another SSH key in the Uberspace dashboard and use that for logging into Uberspace.

Be careful to keep the key number key-X and keep your key ssh-....
Ensure that there is no second line propagating the same SSH key.

command="if [ -t 0 ]; then bash; elif [[ ${SSH_ORIGINAL_COMMAND} =~ ^(scp|rsync|mysqldump).* ]]; then eval ${SSH_ORIGINAL_COMMAND}; else $FORGEJO_HOME/forgejo --config=$FORGEJO_HOME/custom/conf/app.ini serv key-1; fi",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty,no-user-rc,restrict ssh-ed25519 AAAAC... youruser@yourhost

Note

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 isabell@isabell.uber.space:forgejouser/somerepo.git we configure the /home/localuser/.ssh/config file for our local machine with the git ssh key.

Host isabell.uber.space
    User isabell
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

Backup

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

Execute the following command:

[isabell@stardust ~]$ $FORGEJO_HOME/forgejo dump
2024/12/27 17:39:13 ...s/setting/session.go:77:loadSessionFrom() [I] Session Service Enabled
[...]
2024/12/27 17:39:13 cmd/dump.go:265:runDump() [I] Dumping local repositories... /home/isabell/forgejo/data/forgejo-repositories
2024/12/27 17:39:13 cmd/dump.go:306:runDump() [I] Dumping database...
[...]
2024/12/72 17:39:13 cmd/dump.go:430:runDump() [I] Finish dumping in file forgejo-dump-1735313953.zip
[isabell@stardust ~]$

Updates

Note

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_HOME/forgejo migrate
Start the application supervisorctl restart forgejo
Check if the application is running supervisorctl status forgejo

Additional configuration

Forgejo using external renderer (optional)

Forgejo supports custom file renderings (i.e. Jupyter notebooks, asciidoc, etc.) through external binaries to provide a preview.

AsciiDoctors location will be here: $HOME/.gem/ruby/3.2.0/*/asciidoctor*

[isabell@stardust ~]$ gem install asciidoctor
Fetching asciidoctor-2.0.23.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.23
1 gem installed
[isabell@stardust ~]$

Note

Don’t be confused 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_HOME/custom/conf/app.ini with:

[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -e -a leveloffset=-1 --out-file=- -"
IS_INPUT_FILE = false

Tested with Forgejo 9.0.3, Uberspace 7.16.03

Written by: Marc Redwerkz <https://wzrd.pw>