Jesse Laprade

Setting up a Git forge with Gitea

This page guides you through setting up a Git forge using Gitea.

Page overview

Acknowledgements
Reasoning for this guide
Page conventions
Assumptions
Requirements
Preparing your system
Setting up Gitea
Setting up nginx
- Adding a reverse proxy
  - To add a reverse proxy
- Setting up your git domain with certbot
  - To setup up your git domain with certbot
Finalizing your Gitea setup
Tweaking Gitea

Acknowledgements

Most of the documentation found here was referenced from Gitea’s documentation.

Reasoning for this guide

As someone who is learning how to maintain servers and online services, I had a bit of trouble following the documentation, because the documentation for setting up Gitea wasn’t as linear as I was used to. I found myself jumping back and forth between the navigation sidebar, so I decided to create a more linear set of instructions for setting up Gitea for other people who had trouble with setting up Gitea.

Page conventions

Note: Signifies additional information
Tip: Signifies an alternative procedure for completing a step
Warning: Signifies that damage, such as data loss, may occur
Example: Shows how a procedure would be performed in a real scenario
Inline code and code blocks: Signify package names, filenames, file contents, or commands
yourdomain.com: Signifies that you should replace yourdomain.com with your own domain name.

Assumptions

This guide assumes:

You are using a Ubuntu server on a DigialOcean droplet
You are using nginx to serve your web content
You manage your SSL/TLS certificates with certbot
You have your domain name setup with DigitalOcean’s name servers
You have your SSH keys setup with your server
You have root access to your server

Requirements

git
sqlite3
fail2ban

Preparing your system

Before using Gitea, you need to prepare DNS records and create a git user.

This section consists of the following topics:

Setting up DNS records on DigitalOcean
Creating a git user
Adding the git user to your SSH server’s AllowedUsers list
Creating the required directories

Setting up DNS records on DigitalOcean

Setting up DNS records for a git.yourdomain.com allows you to redirect users back to your server, so nginx can redirect users to specific paths or ports on your server.

To setup DNS records on DigitalOcean

Add an A record for git.yourdomain.com to your DigitalOcean droplet
Add an AAAA record for git.yourdomain.com to your DigitalOcean droplet

Creating a git user

Creating a git user allows you to run Gitea as a different user from root. This is a safer option, especially if you intend to push to your repositories using SSH or have multiple users on your Gitea instance.

To create a git user

Run the following command:

sudo adduser \
  --system \
  --shell /bin/bash \
  --gecos 'Git Version Control' \
  --group \
  --disabled-password \
  --home /home/git \
  git

Source: Gitea’s Prepare environment section.

Adding the git user to your SSH server’s AllowedUsers list

Pushing Git commits over SSH is convenient because you don’t need to enter a username and password like you would over HTTPS. You need to add the git user to your SSH server’s AllowedUsers list to use Git over SSH.

To add the git user to your SSH server’s AllowedUsers list

Open /etc/ssh/sshd_config
Find AllowUsers
Add git to list of users

Creating the required directories

Gitea doesn’t have the permissions to create directories in root directories, so you need to do this yourself.

To create the required directories

Run sudo mkdir -p /var/lib/gitea/{custom,data,log}
Run sudo chown -R git:git /var/lib/gitea/
Run sudo chmod -R 750 /var/lib/gitea/
Run sudo mkdir /etc/gitea
Run sudo chown root:git /etc/gitea
Run sudo chmod 770 /etc/gitea

Source: Gitea’s Create required directory structure section.

Setting up Gitea

Gitea simplifies installation by providing a binary. You can download this binary and move it to a globally-accessible directory.

This section contains the following topics:

Downloading Gitea
Installing Gitea
Auto-starting Gitea on system boot

Downloading Gitea

Downloading Gitea provides you with the proper resources for running Gitea.

To download Gitea

Run sudo su git
Run cd
Run wget -O gitea https://dl.gitea.io/gitea/1.13.1/gitea-1.13.1-linux-amd64
Run chmod +x gitea

Note: In this section, we are downloading Gitea version 1.13.1. For the latest version, check out Gitea’s Install from binary section.

Source: Gitea’s Download section.

Installing Gitea

Installing Gitea makes the Gitea binary globally accessible on your system.

To install Gitea

Run cp gitea /usr/local/bin/gitea

Source: Gitea’s Copy Gitea binary to global location section.

Auto-starting Gitea on system boot

Auto-starting Gitea can be convenient if you need to restart your server after updates or changes, and have several other services that you need to auto-start.

To auto-start Gitea on system boot

Add the following in /etc/systemd/system/gitea.service:

[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
###
# Don't forget to add the database service requirements
###
#
#Requires=mysql.service
#Requires=mariadb.service
#Requires=postgresql.service
#Requires=memcached.service
#Requires=redis.service
#
###
# If using socket activation for main http/s
###
#
#After=gitea.main.socket
#Requires=gitea.main.socket
#
###
# (You can also provide gitea an http fallback and/or ssh socket too)
#
# An example of /etc/systemd/system/gitea.main.socket
###
##
## [Unit]
## Description=Gitea Web Socket
## PartOf=gitea.service
##
## [Socket]
## Service=gitea.service
## ListenStream=<some_port>
## NoDelay=true
##
## [Install]
## WantedBy=sockets.target
##
###

[Service]
# Modify these two values and uncomment them if you have
# repos with lots of files and get an HTTP error 500 because
# of that
###
#LimitMEMLOCK=infinity
#LimitNOFILE=65535
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
# If using Unix socket: tells systemd to create the /run/gitea folder, which contains the gitea.sock file
# (manually creating /run/gitea doesn't work, because it would not persist across reboots)
#RuntimeDirectory=gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea
# If you install Git to directory prefix other than default PATH (which happens
# for example if you install other versions of Git side-to-side with
# distribution version), uncomment below line and add that prefix to PATH
# Don't forget to place git-lfs binary on the PATH below if you want to enable
# Git LFS support
#Environment=PATH=/path/to/git/bin:/bin:/sbin:/usr/bin:/usr/sbin
# If you want to bind Gitea to a port below 1024, uncomment
# the two values below, or use socket activation to pass Gitea its ports as above
###
#CapabilityBoundingSet=CAP_NET_BIND_SERVICE
#AmbientCapabilities=CAP_NET_BIND_SERVICE
###

[Install]
WantedBy=multi-user.target

Run sudo systemctl enable gitea
Run sudo systemctl start gitea

Source: Gitea’s Using systemd section.

Setting up nginx

Gitea is a web application, so you need to setup nginx to serve the interface.

This section consists of the following topics:

Adding a reverse proxy
Setting up your git domain with certbot

Adding a reverse proxy

Gitea runs on port 3000 by default, so you need to configure nginx to redirect users to port 3000 on your server when they visit git.yourdomain.com.

To add a reverse proxy

Add the following in /etc/nginx/sites-available/git.yourdomain.com as root:

server {
  listen 80;
  server_name git.yourdomain.com;

  location / {
    proxy_pass http://localhost:3000;
  }
}

Run the following command:

sudo ln -s /etc/nginx/sites-available/git.yourdomain.com /etc/nginx/sites-enabled/git.yourdomain.com

Run sudo systemctl restart nginx

Source: Gitea’s Nginx section.

Setting up your git domain with certbot

Before you can access your website, you need to allow a secure connection before you sign up for the initial Gitea account, which can optionally be used as an administrator account as well as a regular user account.

To setup up your git domain with certbot

Run sudo certbot
Follow the prompts
Run sudo systemctl restart nginx

Finalizing your Gitea setup

Before you can use Gitea, you need to access the web installer. The web installer guides you through a setup process, and user registration. The first user who signs up has the option to become an administrator user who can also use Gitea as a regular user.

This section consists of the following topics:

Accessing the web interface
Removing the write permission for the git user
Setting up fail2ban

Accessing the web interface

Gitea provides a web interface for configuring and installing Gitea. You can access the web interface using a web browser.

To access the web interface

Navigate to git.yourdomain.com/install in your browser

Tip: If this doesn’t work, try navigating to git.yourdomain.com.
Choose SQLite
Change “SSH Server Domain” to git.yourdomain.com
Change “Gitea Base URL” to https://git.yourdomain.com
Choose your desired settings for the remaining configuration options
Click “Install Gitea”

Removing the write permission for the git user

In previous sections, /etc/gitea has write permissions for the git user, so the web installer could write to the configuration file. You should change the permissions back to read-only for security purposes.

To remove the write permission for the git user

Run sudo chmod 750 /etc/gitea
Run sudo chmod 640 /etc/gitea/app.ini

Source: Gitea’s Create required directory structure section.

Setting up fail2ban

fail2ban protects your server against repeated attacks if you have a publicly-facing authentication system, such as a sign-in page or a register page.

In this guide, we disable the registration page, but the sign-in page needs to be protected.

To setup fail2ban

Add the following to /etc/fail2ban/filter.d/gitea.conf as root:

[Definition]
failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
ignoreregex =

Add the following to /etc/fail2ban/jail.d/gitea.conf as root:

[gitea]
enabled = true
filter = gitea
logpath = /var/lib/gitea/log/gitea.log
maxretry = 10
findtime = 3600
bantime = 900
action = iptables-allports

Run touch /var/lib/gitea/log/gitea.log as root
Run systemctl restart fail2ban

Source: Gitea’s Fail2ban setup to block users after failed login attempts page.

Tweaking Gitea

Gitea provides an app.ini file that allows you to modify Gitea to your liking.

This section consists of the following topics:

Disabling registrations
Changing the default branch name
Setting up garbage collection

Disabling registrations

After you created the first user, you can disable registrations to prevent unknown users from registering on your Gitea.

Note: If you wish to add a user in the future, you can use Gitea’s built-in “Create User Account” button found in “Site Administration” > “User Accounts”.

To disable registrations

Edit /etc/gitea/app.ini as root
Find the [service] section

Change DISABLE_REGISTRATION’s value to true

Example: Your [service] section might look like the one below:

[service]
REGISTER_EMAIL_CONFIRM            = false
ENABLE_NOTIFY_MAIL                = false
DISABLE_REGISTRATION              = true
ALLOW_ONLY_EXTERNAL_REGISTRATION  = false
ENABLE_CAPTCHA                    = false
REQUIRE_SIGNIN_VIEW               = false
DEFAULT_KEEP_EMAIL_PRIVATE        = false
DEFAULT_ALLOW_CREATE_ORGANIZATION = false
DEFAULT_ENABLE_TIMETRACKING       = false
NO_REPLY_ADDRESS                  = noreply.localhost

Changing the default branch name

Gitea allows you to set a default branch name when creating new repositories.

To change the default branch name

Edit /etc/gitea/app.ini as root
Find the [repository] section
Change DEFAULT_BRANCH’s value to main
Example: Your [repository] section might look like the one below:
```
[repository]
ROOT = /home/git/gitea-repositories
DEFAULT_BRANCH = main
```
Note: Other common default branch names could be trunk or default

Setting up garbage collection

Setting a garbage collection value prevents incremental memory consumption over time. Setting this keeps CPU usage at a constant level. Without this set, the CPU usage rises over time.

To setup garbage collection

Edit /etc/gitea/app.ini as root
Find the [session] section
Add GC_INTERVAL_TIME = 86400 under PROVIDER = file
Example: Your [session] section might look like the one below:
```
[session]
PROVIDER = file
GC_INTERVAL_TIME = 86400
```