Jump to content
From ArchWiki

Related articles

- Gogs
- Git

Gitea is a community managed fork of Gogs, lightweight code hosting solution written in Go and published under the MIT license.

## Installation

Install the gitea or gitea-gitAUR package. There is also a package for the gitea fork forgejo.

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

See the Gitea docs for more configuration examples.

### PostgreSQL

Install and configure PostgreSQL.

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

Note: When Gitea 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 gitea

Create the Gitea database, owned by `gitea` user:

    [postgres]$ createdb -O gitea gitea

PostgreSQL#Configure PostgreSQL to be accessible from remote hosts

Verify it works:

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

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

    /etc/gitea/app.ini

    DB_TYPE             = postgres
    HOST                = hostadress:port
    NAME                = gitea
    USER                = gitea
    ; 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 gitea

Create the Gitea database, owned by `gitea` user:

    [postgres]$ createdb -O gitea gitea

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    gitea           gitea           peer

Restart `postgresql.service`.

Verify it works:

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

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

    /etc/gitea/app.ini

    DB_TYPE             = postgres
    HOST                = /run/postgresql/
    NAME                = gitea
    USER                = gitea
    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 `gitea` DEFAULT CHARACTER SET `utf8mb4` COLLATE `utf8mb4_unicode_ci`;
    mysql> CREATE USER `gitea`@'localhost' IDENTIFIED BY 'password';
    mysql> GRANT ALL PRIVILEGES ON `gitea`.* TO `gitea`@`localhost`;
    mysql> FLUSH PRIVILEGES;
    mysql> \q

Try connecting to the new database with the new user:

    $ mysql -u gitea -p -D gitea

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

    /etc/gitea/app.ini

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

## Usage

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

When running Gitea 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 Gitea to listen on all interfaces, set `HTTP_ADDR = 0.0.0.0` in `/etc/gitea/app.ini`.

## Tips and tricks

### Local Shell Client (tea)

With tea you can use the official cli-client of gitea. More information can be found at https://gitea.com/gitea/tea

### Enable SSH Support

Make sure SSH is properly configured and running.

#### Setup your domain

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

    /etc/gitea/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, Gitea will run as the user `gitea`; 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 gitea` to it, e.g.:

    /etc/ssh/sshd_config

    ...
    AllowUsers archie gitea
    ...

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 Gitea to bind it on port 22, or if you want to bind Gitea 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/gitea.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 Gitea docs[1] for more detail.

The appearance of gitea is highly customizable using Go templates. First, create the `/var/lib/gitea/custom` directory. Templates can be overridden by editing files in `/var/lib/gitea/custom/templates`. The default templates can be found in the Gitea source code under the `templates` directory. For instance, to customize the home page, copy `templates/home.tmpl` from the source code to `/var/lib/gitea/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/gitea/custom/public/img/logo.svg` and `/var/lib/gitea/custom/public/img/favicon.svg`

Gitea 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 Gitea 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/gitea.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 / {
            proxy_pass http://unix:/run/gitea/gitea.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/gitea/app.ini

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

    [session]
    COOKIE_SECURE              = true

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

#### Apache HTTP Server

The following is an example of using the Apache HTTP Server as reverse proxy for Gitea 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/gitea/gitea.socket|http://domain.tld nocanon
    ProxypassReverse / unix:/run/gitea/gitea.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/gitea/gitea.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/gitea/gitea.socket|http://domain.tld nocanon
    ProxypassReverse /git unix:/run/gitea/gitea.socket|http://domain.tld nocanon

    /etc/gitea/app.ini

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

### Setup for custom data directory

As of now, you cannot use a custom path like `/srv/gitea` as your server home, since the shipped `gitea.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/gitea.service.d/data-directory.conf

    [Service]
    ReadWriteDirectories=/srv/gitea

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

## Troubleshooting

### Database error on startup after upgrade to 1.5.0

A problem can appear after the upgrade to 1.5.0. The service will not start, and the following error is present in the logs:

    /var/log/gitea/gitea.log

    2018/08/21 16:11:12 [...itea/routers/init.go:60 GlobalInit()] [E] Failed to initialize ORM engine: migrate: do migrate: Sync2: Error 1071: Specified key was too long; max key length is 767 bytes

To fix this problem, run the following command as the `root` user on your MySQL/MariaDB server

    $ mysql -u root -p

    MariaDB> set global innodb_large_prefix = `ON`;

gitea should stop complaining about key size and startup properly.

## See also

- Gitea Documentation

Category:

- Git web interfaces