Forgejo - ArchWiki

Jump to content
Toggle the table of contents

# Forgejo

1 language

- 日本語

From ArchWiki

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-gitAUR 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`.

You will need to change the permissions of of the folder as well as the app.ini file:

    # chown root:forgejo /etc/forgejo
    # chown root:forgejo /etc/forgejo/app.ini
    # chmod g+w /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 `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 Gitea

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 Gitea 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                   = 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 gitea 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/gitea/app.ini

    [server]
    PROTOCOL                   = 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 gitea 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                   = 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

Category:

- Git web interfaces