Forgejo

Related articles

• Gitea
• Gogs
• Git

Forgejo is a hard fork of Gitea managed by the non-profit organization Codeberg, lightweight code hosting solution written in Go and published under the MIT license.

Installation

Install the forgejo or forgejo-git^AUR package.

Forgejo requires the use of a database backend, the following are supported:

• MariaDB/MySQL
• PostgreSQL
• SQLite
• MSSQL

Configuration

The user configuration file is located at /etc/forgejo/app.ini.

See the Forgejo docs for more configuration examples.

If you are migrating from Gitea see the migration guide for Forgejo

PostgreSQL

Install and configure PostgreSQL.

Choose between TCP or UNIX Socket, and jump to the corresponding section.

Note: When Forgejo and PostgreSQL are on the same machine, you should use a Unix socket, as it is faster and more secure.

With TCP socket

Create the new user while connecting to the server as postgres user (you will be prompted for a password for the new user):

[postgres]$ createuser -P forgejo

Create the Forgejo database, owned by forgejo user:

[postgres]$ createdb -O forgejo forgejo

PostgreSQL#Configure PostgreSQL to be accessible from remote hosts

Verify it works:

$ psql --host=ip_address --dbname=forgejo --username=forgejo --password

Configure Forgejo either through the first-run installer or update app.ini:

/etc/forgejo/app.ini

DB_TYPE             = postgres
HOST                = hostadress:port
NAME                = forgejo
USER                = forgejo
; Use PASSWD = `your password` for quoting if you use special characters in the password.
PASSWD              = password

With Unix socket

Create the new user while connecting to the server as postgres user:

[postgres]$ createuser forgejo

Create the Forgejo database, owned by forgejo user:

[postgres]$ createdb -O forgejo forgejo

Setup the Unix socket by adding the following line to /var/lib/postgres/data/pg_hba.conf:

/var/lib/postgres/data/pg_hba.conf

local    forgejo           forgejo           peer

Restart postgresql.service.

Verify it works:

[forgejo]$ psql --dbname=forgejo --username=forgejo

Configure Forgejo either through the first-run installer or update app.ini:

/etc/forgejo/app.ini

DB_TYPE             = postgres
HOST                = /run/postgresql/
NAME                = forgejo
USER                = forgejo
PASSWD              =

MariaDB/MySQL

Note: MySQL socket support can be enabled by using /var/run/mysqld/mysqld.sock as the listen address.

The following is an example of setting up MariaDB, setting your desired password:

$ mysql -u root -p

mysql> CREATE DATABASE `forgejo` DEFAULT CHARACTER SET `utf8mb4` COLLATE `utf8mb4_unicode_ci`;
mysql> CREATE USER `forgejo`@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON `forgejo`.* TO `forgejo`@`localhost`;
mysql> FLUSH PRIVILEGES;
mysql> \q

Try connecting to the new database with the new user:

$ mysql -u forgejo -p -D forgejo

Configure MariaDB either through the first-run installer or update app.ini:

/etc/forgejo/app.ini

DB_TYPE  = mysql
HOST     = 127.0.0.1:3306 ; or /var/run/mysqld/mysqld.sock
NAME     = forgejo
USER     = forgejo
PASSWD   = password

MSSQL

The database must be created with collation _CS_AS (Case-sensitive, accent-sensitive)

Such as:

TSQL

CREATE DATABASE forgejo
COLLATE SQL_Latin1_General_CP1_CS_AS;

Configure MSSQL either through the first-run installer or update app.ini

/etc/forgejo/app.ini

DB_TYPE  = mssql
HOST     = 10.0.0.2:1433 ;Update IP Address
NAME     = forgejo
USER     = forgejo
PASSWD   = password

Usage

Start/enable forgejo.service, the webinterface should listen on http://localhost:3000.

When running Forgejo for the first time, it should redirect to http://localhost:3000/install.

Note:

• You might want to configure a reverse proxy to access remotely, e.g. nginx.
• If you want Forgejo to listen on all interfaces, set HTTP_ADDR = 0.0.0.0 in /etc/forgejo/app.ini.

Tips and tricks

Local Shell Client (forgejo)

Forgejo comes packages with a local shell administration tool. Binary is located in /bin/forgejo

More information can be found at https://forgejo.org/docs/latest/admin/command-line/

Enable SSH Support

Make sure SSH is properly configured and running.

Setup your domain

You might want to set SSH_DOMAIN, e.g.:

/etc/forgejo/app.ini

SSH_DOMAIN                 = git.domain.tld

Note: If you set the PROTOCOL to be http+unix, then you need to unset LOCAL_ROOT_URL or set it to http://unix/. See this comment

Configure SSH

By default, Forgejo will run as the user forgejo; this account will also be used for ssh repository access. For ssh access to work, you have to enable PAM. Alternatively, you might have to unlock service account.

/etc/ssh/sshd_config

...
UsePAM yes
...

If you use AllowUsers in your SSH configuration, add AllowUsers forgejo to it, e.g.:

/etc/ssh/sshd_config

...
AllowUsers archie forgejo
...

Restart sshd.service if you use it (nothing to do if you use sshd.socket).

Disable HTTP protocol

By default, the ability to interact with repositories by HTTP protocol is enabled. You may want to disable HTTP-support if using SSH, by setting DISABLE_HTTP_GIT to true.

Binding on restricted ports

If you use the built-in SSH server and want Forgejo to bind it on port 22, or if you want to bind Forgejo webserver directly on ports 80/443 (that is in a setup without proxy), you will need to add a drop-in systemd unit override:

/etc/systemd/system/forgejo.service.d/override.conf

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
PrivateUsers=false

Enable Dark Theme

In the ui section, you can set the DEFAULT_THEME to arc-green for making the web interface use a dark background.

Customize the appearance of Forgejo

See the Forgejo docs[1] for more detail.

Note: Forgejo does not officially support customizing the interface as it may result in broken interfaces. See https://forgejo.org/docs/latest/admin/customization/#a-word-of-warning-here-be-dragons for more details.

The appearance of forgejo is highly customizable using Go templates. First, create the /var/lib/forgejo/custom directory. Templates can be overridden by editing files in /var/lib/forgejo/custom/templates. The default templates can be found in the Forgejo source code under the templates directory. For instance, to customize the home page, copy templates/home.tmpl from the source code to /var/lib/forgejo/custom/templates/home.tmpl and edit the template as desired.

In addition, the logo and favicon can be changed by creating the following files: /var/lib/forgejo/custom/public/img/logo.svg and /var/lib/forgejo/custom/public/img/favicon.svg

Forgejo needs to be restarted after any changes to these files.

Configure reverse proxy

For additional information and examples, see the Reverse Proxies section on the Forgejo documentation website [2].

nginx

The following is an example of using nginx as reverse proxy for Forgejo over unix socket (you need to provide the SSL certificate):

/etc/nginx/servers-available/forgejo.conf

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name git.domain.tld;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        client_max_body_size 512M;
        proxy_pass http://unix:/run/forgejo/forgejo.socket;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Update the [server] and [session] section of app.ini:

/etc/forgejo/app.ini

[server]
PROTOCOL                   = http+unix
DOMAIN                     = git.domain.tld
ROOT_URL                   = https://git.domain.tld
HTTP_ADDR                  = /run/forgejo/forgejo.socket
LOCAL_ROOT_URL             =

[session]
COOKIE_SECURE              = true 

Note: You do not need to activate any SSL certificate options in /etc/forgejo/app.ini.

Apache HTTP Server

The following is an example of using the Apache HTTP Server as reverse proxy for Forgejo over unix socket. To forward domain.tld to the Forgejo server, use

/etc/httpd/conf/httpd.conf

ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
Proxypass / unix:/run/forgejo/forgejo.socket|http://domain.tld nocanon
ProxypassReverse / unix:/run/forgejo/forgejo.socket|http://domain.tld nocanon

where domain.tld should be replaced by your domain name (this entry is only passed as a header to the proxy, and does not seem to matter for this setup).

/etc/forgejo/app.ini

[server]
PROTOCOL                   = http+unix
DOMAIN                     = domain.tld
ROOT_URL                   = https://domain.tld
HTTP_ADDR                  = /run/forgejo/forgejo.socket
LOCAL_ROOT_URL             =

To forward a subpath such as domain.tld/git to the Forgejo server, use

/etc/httpd/conf/httpd.conf

<Proxy *>
  Order allow,deny
  Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
Proxypass /git unix:/run/forgejo/forgejo.socket|http://domain.tld nocanon
ProxypassReverse /git unix:/run/forgejo/forgejo.socket|http://domain.tld nocanon

/etc/forgejo/app.ini

[server]
PROTOCOL                   = http+unix
DOMAIN                     = domain.tld
ROOT_URL                   = https://git.domain.tld
HTTP_ADDR                  = /run/forgejo/forgejo.socket
LOCAL_ROOT_URL             =

Setup for custom data directory

As of now, you cannot use a custom path like /srv/forgejo as your server home, since the shipped forgejo.service unit file marks everything read-only.

To enable these custom paths, create a drop-in snippet with your server home directory as a new ReadWriteDirectories directive:

/etc/systemd/system/forgejo.service.d/data-directory.conf

[Service]
ReadWriteDirectories=/srv/forgejo

Then do a daemon-reload and restart forgejo.service for the changes to take effect.

Troubleshooting

Service failing with permission denied

If you manually create the forgejo user with a usual home folder /home/forgejo the forgejo service will not start and output an error like :

Sep 04 04:44:32 systemd[1]: forgejo.service: Failed with result 'exit-code'.
Sep 04 04:44:32 systemd[1]: forgejo.service: Main process exited, code=exited, status=200/CHDIR
Sep 04 04:44:32 (forgejo)[30727]: forgejo.service: Failed at step CHDIR spawning /usr/bin/forgejo: Permission denied
Sep 04 04:44:32 (forgejo)[30727]: forgejo.service: Changing to the requested working directory failed: Permission denied

The service needs the home folder of the user to be the main forgejo folder, the default being /var/lib/forgejo a fix would be:

$ usermod -d /var/lib/forgejo forgejo

See also

• Forgejo Documentation