Gitea - ArchWiki

# Gitea

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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.

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`. Do not edit the main configuration file (`/var/lib/gitea/conf/app.ini`), since this file is included in the binary and will be overwritten on each update.

Gitea repository data will be saved into `/var/lib/gitea/repos/`. It is possible to overrule this location in `/etc/gitea/app.ini`, if you do so you might need to edit `ReadWritePaths` in the systemd service file.

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:

    /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`:

    local    gitea           gitea           peer

Restart `postgresql.service`.

Verify it works:

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

Configure Gitea:

    /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 on first run 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.
Note: 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 user `gitea`, as well this account will 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.

### Configure nginx as reverse proxy

This article or section needs expansion.

Reason: Missing Apache HTTP Server/Caddy proxy example (Discuss in Talk:Gitea#)

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;
        }
    }

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

For additional information and examples see Reverse Proxies section on Gitea documentation website [1].

## 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.

### Process dumped core on ArchLinux ARM

Note: This configuration change has been in version 1.12.4-2

A problem can appear after pushing new repo. In web UI repo stay uninitialized, and the following error is present in the system journal:

    # journalctl

    Jun 06 14:34:20 rpi-srv systemd-coredump[5724]: Process 5722 (cat) of user 986 dumped core.

                                                    Stack trace of thread 5722:
                                                    #0  0x0000000076f06e58 posix_fadvise64 (libc.so.6 + 0xd2e58)

To fix this problem, override `gitea.service`:

    # systemctl edit gitea

    [Service]
    SystemCallErrorNumber=EPERM

## See also

- Gitea Documentation

Category:

- Git web interfaces

Hidden category:

- Pages or sections flagged with Template:Expansion