m455.casa

Setting up a Git forge with Gitea

2021-01-06

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

Page overview

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

Assumptions

This guide assumes:

Requirements

Preparing your system

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

This section consists of the following topics:

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

  1. Add an A record for git.yourdomain.com to your DigitalOcean droplet
  2. 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

  1. 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 will 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

  1. Open /etc/ssh/sshd_config
  2. Find AllowUsers
  3. Add git to list of users

Creating the required directories

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

To create the required directories

  1. Run sudo mkdir -p /var/lib/gitea/{custom,data,log}
  2. Run sudo chown -R git:git /var/lib/gitea/
  3. Run sudo chmod -R 750 /var/lib/gitea/
  4. Run sudo mkdir /etc/gitea
  5. Run sudo chown root:git /etc/gitea
  6. 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

Downloading Gitea will provide you with the proper resources for running Gitea.

To download Gitea

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

Note: In this section, we are downloading Gitea version 1.13.1. This guide will quickly become outdated. For the latest version, check out Gitea’s Install from binary section.

Source: Gitea’s Download section.

Installing Gitea

Installing Gitea will make the Gitea binary globally accessible on your system.

To install Gitea

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

  1. 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 will contain 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
  2. Run sudo systemctl enable gitea

  3. Run sudo systemctl start gitea

Source: Gitea’s Using systemd section.

Setting up nginx

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

This section consists of the following topics:

Adding a reverse proxy

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

To add a reverse proxy

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

  2. Run the following command:

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

  3. Run sudo systemctl restart nginx

Source: Gitea’s Nginx section.

Setting up your git domain with certbot

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

To setup up your git domain with certbot

  1. Run sudo certbot

  2. Follow the prompts

  3. Run sudo systemctl restart nginx

Finalizing your Gitea setup

Before you can use Gitea, you will need to access the web installer. The web installer will guide 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

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

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

    Tip: If this doesn’t work, try navigating to git.yourdomain.com.

  2. Choose your desired settings

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

  1. Run sudo chmod 750 /etc/gitea
  2. 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, although we will be disabling the registration page, there will still be a sign-in page that we need to protect.

To setup fail2ban

  1. 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 =

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

  3. Run service fail2ban restart

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

Setting up sendmail

sendmail allows your server to send email to users when you create an account for them, or they sign up, if you have sign-ups enabled. sendmail also allows your server to help users when they need to reset their password through email.

To setup sendmail

  1. Add the following to /etc/gitea/app.ini as root:

    [mailer]
ENABLED       = true
FROM          = gitea@mydomain.com
MAILER_TYPE   = sendmail
SENDMAIL_PATH = /usr/sbin/sendmail

  2. Run sudo systemctl restart gitea

  3. Navigate to https://git.yourdomain.com/

  4. Navigate to “Site Administration” > “Configuration” > “SMTP Mailer Configuration”

  5. Send a test email

Source: Gitea’s Sendmail version 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

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

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

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

  1. Edit /etc/gitea/app.ini as root
  2. Find the [repository] section

  3. 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 will prevent 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

  1. Edit /etc/gitea/app.ini as root
  2. Find the [session] section

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