Getting Started with Gitea

Setting Up Gitea on Your Local Server: A Comprehensive Guide

7 min readJun 2, 2024

The core component of CI/CD (Continuous Integration and Continuous Delivery) infrastructure is the code repository platform, such as GitHub, GitLab, BitBucket, or Gitea. This article focuses on Gitea due to its cost-effectiveness, as it is free, and will guide you through setting it up on your own local server.

Setting up Gitea can be a unique challenge since it lacks pre-packaged system distributions. Unlike system packages (.deb or .rpm) that not only install the application but also automate the setup of a least privilege user and group, default directory structure, configuration, and system startup scripts like a systemd unit, this tutorial will show you how to manually configure all of these elements for Gitea.

Linux Guest System (optional)

These instructions are compatible with any Debian or Ubuntu distribution. You can optionally utilize a virtual machine guest to create the Linux environment.

An easy way is to use Vagrant to easily bring up a virtual guest running Ubuntu, for example.

If you have an Intel-based system, you can use the default provider Virtualbox on Windows, macOS, and Linux. For the new macOS systems, including Macbooks running on Apple Silicon (ARM64), you can use Vagrant with QEMU and the vagrant-qemu plugin.

Virtualization Required Tools

These are the tools needed to run virtual guests.

For Intel/AMD based systems, running Windows, Linux, or macOS, you will need these tools:

Management Tools: Vagrant
Virtualization: Virtualbox

For macOS running on either Apple Silicon (AMD64) or Intel, you will need the following:

Management Tools: Vagrant, QEMU
Virtualization: HVF bundled with macOS (no install needed)
Vagrant Plugin: vagrant-qemu

Virtualization Guest Box Images

The box images used in this guide (downloaded automatically) are generic/ubuntu2204 for Intel and perk/ubuntu-2204-arm64 for ARM64.

I have not tested these images, but if you wanted to use Debian instead, you can use generic/debian12 for Intel or perk/debian-11-genericcloud-arm64 for ARM64.

macOS Installation Notes

If you have Homebrew, you can install these tools with

# install vagrant
brew tap hashicorp/tap
brew install hashicorp/tap/hashicorp-vagrant

# install virtualbox (optional for Intel Macintosh)
brew install virtualbox

# install QEMU (required for Macintosh w Apple Silicon)
brew install qemu
vagrant plugin install vagrant-qemu

Windows Installation Notes

If you have a tool like Chocolatey installed, you can install the tools with following

# install Vagrant
choco install vagrant

# install Virtualbox
choco install virtualbox

Note that some Windows versions, Microsoft bundles Hyper-V. virtualization solution, which will work with Vagrant and the box image generic/ubuntu2204. For Windows Home users, where Microsoft restricts installation of this solution, you can use Virtualbox, or alternatively use WSL (Windows Subsystem for Linux).

Configuring Vagrant

Below is a Vagrantfile configuration that works for either Virtualbox on Windows, Linux, and macOS running on Intel. It will also works with QEMU on macOS on either Intel or Apple Silicon (ARM64) processors.

# Vagrantfile
Vagrant.configure("2") do |config|
  if RUBY_PLATFORM =~ /^x86_64/
    # use qemu/virtualbox image for x86_64
    config.vm.box = "generic/ubuntu2204"
    if RUBY_PLATFORM =~ /darwin$/
      # configure QEMU/HVF if qemu provider
      config.vm.provider "qemu" do |qe|
        qe.ssh_port = "50025" # change ssh port as needed
        qe.qemu_dir = "/usr/local/share/qemu"
        qe.arch = "x86_64"
        qe.machine = "q35,accel=hvf"
        qe.net_device = "virtio-net-pci"
      end
    end
  elsif RUBY_PLATFORM =~ /^arm64.?-darwin.*$/
    # arm64 image for macOS on Apple Silicon
    config.vm.box = "perk/ubuntu-2204-arm64"
    # configure QEMU/HVF if qemu provider
    config.vm.provider "qemu" do |qe|
      qe.ssh_port = "50026" # change ssh port as needed
    end
  end
end

Vagrant is written in Ruby and so its configuration is evaluated Ruby code. The provider for the virtualization system can be specified with the --provider command-line argument, or if none are specified, it defaults to virtualbox. The above Vagrantfile configuration will select the best options for the provider you specify.

Using Virtualbox (macOS, Linux, Windows)

If you wish to use Virtualbox, you can download the image and bring up the virtual guest with following command:

# start virtual guest using Virtualbox default
vagrant up --provider=virtualbox

Using Hypervisor.framework (macOS only)

If you installed the QEMU and the vagrant-qemu plugin, you can bring up that environment that uses Hypervisor.framework (HVF) with the following command below:

# use vagrant-qemu plugin (https://github.com/ppggff/vagrant-qemu)
vagrant up --provider=qemu

Note with this setup, if you have problems with the port already in use, whether it is the web port 3000 or with the QEMU provider, the ssh port of 50025 or 50026, you can test to see what service is locking the port using lsof.

lsof -nP -iTCP:3000

Installing Gitea

Run these instructions on the target Ubuntu or Debian based system, such as the virtual guest.

If you are using vagrant, then type the following to login into the virtual guest before running these instructions:

vagrant ssh

Install Database and Dependencies

sudo apt update
export DEBIAN_FRONTEND=noninteractive
export DEBIAN_PRIORITY=critical
sudo apt install -y git sqlite3

Create a User for Gitea

Below will setup a user with least privilege. The Gitea service should never run as root. This is how you can do this on Debian and Ubuntu systems:


if grep -q debian /etc/os-release; then
  # Create Gitea user on Debian or Ubuntu
  sudo adduser \
     --system \
     --shell /bin/bash \
     --gecos 'Git Version Control' \
     --group \
     --disabled-password \
     --home /home/git \
     git
fi

For RHEL and Fedora based distros, see Installation from binary for further instructions on this step. For other distros or operating systems, you’ll need to consult man pages or documentation for those systems.

Download and Install

This will allow you to download and install the Gitea binary securely:

GITEA_VERS="1.22"
GITEA_ARCH="$(dpkg --print-architecture)"
GITEA_PKG_NAME="gitea-${GITEA_VERS}-linux-${GITEA_ARCH}"
GITEA_DOWNLOAD_URL="https://dl.gitea.io/gitea/$GITEA_VERS/$GITEA_PKG_NAME"

# Download Binary and corresponding signature
curl -sLO $GITEA_DOWNLOAD_URL
curl -sLO $GITEA_DOWNLOAD_URL.asc

# Install Gitea public key used to sign binaries
gpg --keyserver keys.openpgp.org \
  --recv 7C9E68152594688862D62AF62D9AE806EC1592E2

# if valid binary, install binary
if gpg --verify $GITEA_PKG_NAME.asc $GITEA_PKG_NAME; then
  chmod +x $GITEA_PKG_NAME
  mv $GITEA_PKG_NAME /usr/local/bin/gitea
fi

Setup Directory structure

Below is how you can setup the required directory structure and ownership that Gitea will run under a non-root user account.

sudo mkdir -p /var/lib/gitea/{custom,data,indexers,public,log}

sudo chown -R git:git /var/lib/gitea/
sudo chown -R git:git /var/lib/gitea/
sudo mkdir /etc/gitea
sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea

Service Configuration

In any operating system there a facility to manage services. On most Linux distros today, systemd is that system. These steps download an configure a systemd unit configuration (gitea.service) and then enable and start the Gitea service. This service will run as the git user.

sudo wget https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/systemd/gitea.service \
  -P /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now gitea

sudo systemctl status gitea

Firewalls

If a local firewall is enabled, we can allow traffic to the Gitea service with:

sudo ufw allow 3000/tcp

For other distros and operating systems, consult their documentation how to configure firewalls on those systems.

Configure Gitea

After this, go to the web browser and point it to http://localhost:3000. Fill out the form with these values below:

* Database Settings:
  * Database Type: SQLite3
  * Path: Use an absolute path, /var/lib/gitea/data/gitea.db
* Application General Settings:
  * Site Title: Enter your organization name.
  * Repository Root Path: var/lib/gitea/data/gitea-repositories.
  * Git LFS Root Path: /var/lib/gitea/data/lfs.
  * Run As Username: git
  * SSH Server Domain: localhost
  * SSH Port: 22
  * Gitea HTTP Listen Port: 3000
  * Gitea Base URL: http://localhost:3000/
  * Log Path: /var/lib/gitea/log

This might looking something like this:

Afterward, click on the “Install Gitea” button

Create Admin User Gitea

After the initial configuration screen, you will be redirected to a login page. Register a new user, such as bob, which will be automatically added to the admin group.

Secure the Configuration

On the guest system, secure the configuration by making it read-only:

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

Conclusion

The primary goal of this article is to provide an introduction to Gitea and guide you through its setup. This foundation will be useful for future articles related to CI/CD, particularly where integrating with a managed git server, like Gitea, is crucial for solutions like Spinnaker, FluxCD or ArgoCD.

Additionally, this article aims to impart systems engineering knowledge, focusing on how to bootstrap a service and apply the principle of least privilege. These essential skills for system administrators and systems engineers are not typically covered in formal courses. Therefore, the best ways to acquire this knowledge are through tutorials like this one, occasional documentation such as that provided by Gitea, and inspecting system packages like .deb files on Debian or Ubuntu, or .rpm files on RHEL or Fedora.

A third goal is to demonstrate how easy it is to use virtualization to test out systems using Vagrant and virtualization solutions like Virtualbox or QEMU.

Resources

You can add a Kubernetes cluster next to Gitea, allowing for easy experimentation with gitops.

Getting Started with Kubeadm

Using Kubeadm to install Kubernetes on a local server

joachim8675309.medium.com

Gitea Articles

How to install the self-hosted Git server Gitea on Ubuntu 18.04 [video] by Tech Republic: video on how to set this up on Ubuntu with MySQL. There are some errors in the instructions that leads to insecure setup using the root account.
How to Install Gitea on Ubuntu 20.04 by Linuxize on May 7, 2021 covers the similar material, but also demonstrates how to use a reverse proxy with Nginx with TLS certificates that sits in front of Gitea.