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
- Reasoning for this guide
- Page conventions
- Assumptions
- Requirements
- Preparing your system
- Setting up Gitea
- Setting up nginx
- 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: Notes signify additional information.
- Tip: Tips signify an alternative procedure for completing a step.
- Warning: Warnings signify that damage, such as data loss, may occur.
- Example: Examples provide a reference of how a procedure would be performed in the real world.
Inline code
: Inline code signifies package names, filenames, or command-line utilities.Code block
: Code blocks signify file contents.yourdomain.com
: Signifies you should replaceyourdomain.com
with your 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
- sqlite
- sendmail
- fail2ban
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
- 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 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
- 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 will have 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
Downloading Gitea will provide 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. 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
- 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 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
- 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 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
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 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
Run
sudo certbot
Follow the prompts
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
- Removing the write permission for the git user
- Setting up fail2ban
- Setting up sendmail
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 browserTip: If this doesn’t work, try navigating to
git.yourdomain.com
.Choose your desired settings
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, although we will be disabling the registration page, there will still be a sign-in page that we need to protect.
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
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
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
Run
sudo systemctl restart gitea
Navigate to
https://git.yourdomain.com/
Navigate to “Site Administration” > “Configuration” > “SMTP Mailer Configuration”
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
- Edit
/etc/gitea/app.ini
as root - Find the
[service]
section Change
DISABLE_REGISTRATION
’s value totrue
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 tomain
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
ordefault
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
- Edit
/etc/gitea/app.ini
as root - Find the
[session]
section Add
GC_INTERVAL_TIME = 86400
underPROVIDER = file
Example: Your
[session]
section might look like the one below:[session] PROVIDER = file GC_INTERVAL_TIME = 86400