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 GPLv3+ license.
Installation
Install
the
forgejo
or
forgejo-git
AUR
package.
Forgejo requires the use of a database backend, the following are supported:
PostgreSQL
MariaDB
/
MySQL
SQLite
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
[database]
DB_TYPE             = postgres
NAME                = forgejo
USER                = forgejo
PASSWD              =
password
HOST                =
hostadress:port
Note
If your password contains spaces or special characters you can surround it in quotes.
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
[database]
DB_TYPE             = postgres
NAME                = forgejo
USER                = forgejo
PASSWD              =
password
HOST                = /run/postgresql/
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
[database]
DB_TYPE  = mysql
HOST     = 127.0.0.1:3306 ; or /var/run/mysqld/mysqld.sock
NAME     = forgejo
USER     =
forgejo
PASSWD   =
password
SQLite
No specific configuration needed for SQLite itself.
Configure SQLite either through the first-run installer or update
app.ini
:
/etc/forgejo/app.ini
[database]
DB_TYPE = sqlite3
PATH= /var/lib/forgejo/data/forgejo.db
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
under the
[server]
section.
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
[server]
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.
By default this user will be expired and you may encounter an error when authenticating: "Your account has expired; please contact your system administrator".
Use
chage
to remove the expiration condition, e.g. as follows:
# chage -E -1 forgejo
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
in
/etc/forgejo/app.ini
under the
[repository]
section.
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
forgejo-dark
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;
    listen [::]:443 ssl;
    http2 on;
    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