Self-Hosting Gitea

Gitea is a fantastic, simple Git hosting platform for a variety of use cases. For the individual, having sensitive code contained on a self-hosted instance of Gitea could allow for projects and code to be stored which might be inappropriate for hosting on larger third-party platforms such as Gitlab or Github.

Gitea is available for a variety of platforms (Windows or Linux, to name a couple) and architectures, such as x86, amd64, and various arm builds to support the Raspberry Pi.

Gitea is written in Golang and requires only the installation of a single binary or the use of a Docker container. This tutorial will focus on the deployment when not using Docker.

Install Pre-Requisites

Gitea can run with a number of different database backends, most notably:

• MySQL
• SQLite
• PostgreSQL

This tutorial will leverage SQLite, which is completely approrpriate for an at-home self-hosted instance. For deploying on the public Internet for shared use, using a dedicated database server will provide for better performance for multiple concurrent users.

Using SQLite, no database engine needs to be installed; the database will be created when Gitea is first run.

Git does need to be installed via any means. The simplest means would be through a package manager. For Debian or Debian-derived distributions, using apt-get install git would be sufficient.

Create System-Level Items

Two types of items need created for a Gitea installation:

1. a dedicated git user for backend management of the stored Git repositories.
2. various directories to store the files

Git User

This user will be used by all Git-related backend operations, including maintenance of repositories on the server and all git pushes and pulls from remote users of Gitea.

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

The home directory for this new ‘git’ user will also house the data from the uploaded Git repositories.

File Structure

Gitea can be run from a single directory in any user’s home folder, and this can be very useful for running quick reviews of new versions or testing something which has the potential to be very problematic. For deployment in production, various system-level locations should be created to store the various bits of Gitea’s application.

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

The directories beneath /var/lib/gitea contain the locations of the HTML files for Gitea and their lkogs. As usual, the ‘/etc/gitea’ directory would contain configuration settings for Gitea.

Create Service Configuration File

Before the tutorial is complete, Gitea will be running as a system service. However, the initial run will be completed using a manual execution of the Gitea binary. In preparation of running Gitea as a system service, the configuration file can be created for systemd.

The contents of the service file can be found at https://github.com/go-gitea/gitea/blob/main/contrib/systemd/gitea.service. These contents should be reviewed and then added into a new file at /etc/systemd/system/gitea.service. After edits are made to the service file, it can be added to systemd and can be set to start on first boot.

Download and Deploy Gitea

Gitea is most easily downloaded from the main website’s [download browser](gitea | Gitea), although the same files can also be found on Github. On Linux, the actual application downloads have no file extension and have a filename to describe the version, operating system, and CPU architecture on which it runs. In the case of a 64-bit Linux operating system on an Intel or AMD chip, copy the URL of the file named gitea-<version>-linux-amd64. At the time of this writing, the version is 1.16.4, so the proper filename is gitea-1.16.4-linux-amd64.

To download the file to the server where Gitea is being run, copy the URL where the file is located to the clipboard. Then, from the command line of the new server waiting for this install, type wget <address>. This will download the full Gitea binary to a folder on the new Gitea server.

After downloading the release, the file should be checked to confirm that the downloaded binary matches the author(s) using md5sum or sha256 hashes. This avoids the opportunity to malicious code to be installed on the Gitea server.

Next, the binary need to be installed into the desired location, such as /usr/local/bin. This is done with a copy command which also renames the version-specific filename to a consistent filename which can be used by the service file later. Also, the permissions need to be changed so that the binary can be run by the ‘git’ user created earlier in this process.

sudo cp gitea-<version>-linux-amd64 /usr/local/bin/gitea
sudo chmod a+x /usr/local/bin/gitea

First Run

The first time Gitea is run, it will detect that no proper configuration file has been created and launch an installer mode. To ensure we can install the application with the proper locations pre-configured, we can run Gitea manually with a modified command line.

The GITEA_WORK_DIR tells Gitea where all of the data used by the users of the application will be located, along with the log files which can be used to diagnose problems in the future. In the case of a SQLite database, this is also where that database would be located.

After the actual call to the newly-installed Gitea binary, we use the -c flag to specify where the app’s configuration file would be located. In this case, the app.ini configuration file is created in /etc/gitea which is where the service configuration file has specified this file will be when run under normal operation.

GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini

By running the command above, Gitea is started on port 3000 of the system on which Gitea is being installed.

Initial Configuration

To configure Gitea, a web browser is used, primarily. The address to browse to the installation page is:

http://<ip address of Gitea server>:3000

On this page, just a few options need updating to complete the installation. The table below describes the various settings which need reviewed or updated:

Optionally, the section at the bottom titled ‘Administrator Account Settings’ could be used to pre-define an administrator account for Gitea, but it is easy to also register the first user of the system who automatically becomes an administrator.

After changing the appropriate settings, select ‘Install Gitea’ and allow Gitea to install iteself; this should take seconds, as it is really only checking that all paths are writable, setting the initial database schema, and writing the app.ini configuration file. If an administrator account was not specified during the Installation Wizard, it would be best to proceed to register the first account on the system to create the administrative user.

Now that /etc/gitea/app.ini has been generated and an administrator has been created, we need to shut down Gitea from this initial run so we can make one additional optional adjustment and start up Gitea normally. To stop Gitea, use Ctrl-C on the console running Gitea to indicate the desire to stop the application. If the console is not available, the below command will terminate Gitea in a healthy fashion and allow for proper shutdown:

killall -15 gitea

Many open-source projects are beginning to change the name of the default branch of their Git repositories. Without dipping into the reasoning for this, a single change to the configuration file can enable this change, if desired. Using a text editor, modify /etc/gitea/app.ini to add the following line:

DEFAULT_BRANCH = main

Additional settings are available in this file, most impotantly settings for SSL certificates. While outside the scope of this tutorial, enabling SSL certificates is one of the most basic security measures recommended, especially of this is being installed on the public Internet. If the intent is to run Gitea locally inside a home lab, a standard HTTP installation may be appropriate.

Switching to Normal Operation

Switching to normal operation is a very straightforward process for those who have run other services via systemd. Two commands will enable the service to start at boot and start the service right away.

sudo systemctl enable gitea
sudo systemctl start gitea

At this point, the service should be running and available at the URL from the installation setup wizard on port 3000.

http://<server URL>:3000/

Upgrades

Upgrades are fairly simple with this setup.

wget https://dl.gitea.io/gitea/<version>/gitea-<version>-<platform>-<arch>amd64
sudo systemctl stop gitea
sudo cp gitea-<version>-<platform>-<arch> /usr/local/bin/gitea
sudo chmod a+x /usr/local/bin/gitea
sudo systemctl start gitea

After the upgrade, browse to the URL of your Gitea instance, in case there are database schema updates, although there rarely are.

Conclusion

At this point, the Gitea server should be up and running and ready for use in a home lab or as a personal or small to mid-sized project Git hosting service. The next obvious steps to explore, outside the scope of this document, would be to obtain SSL certificates and configure Gitea, to review the various configuration options in the administrative panels, and to look into the various tools for organizing work, including issues, milestones, and project boards.