I have been using a Raspberry Pi as private Git server for several years to store the different versions of publications and software scripts I write. Recently, I switched from the very simple Gitolite to Gitea. While Gitolite was doing it’s job well and generally did not cause any trouble, I always missed an interface for easy overview and administration of the repositories. Therefore, I’m glad to have Gitea up and running as the software offers all features I was looking for.
During installation of Gitea, I found many installation guides to be incomplete in some details. Therefore, this article is another (hopefully more complete) guide on how to install Gitea on a Raspberry Pi.
If you feel like I missed some important detail or found any error, let me know via the contact form.
Pre-requisites
In the following, it is assumed that you have a Raspberry Pi (RPi) with Raspberry Pi OS installed. I was using a Raspberry Pi 3 B+ while the single installation steps should also work for other versions.
Before we start, make sure that the software on the RPi is up to date by running:
sudo apt update
sudo apt upgrade
Furthermore, Gitea requires the Git package to be installed. Check if Git is already installed with
git --version
and install it if necessary with the help of the package manager:
sudo apt install git
Install a database
Gitea requires a database to handle the user and system data. According to the documentation, PostgreSQL, MySQL, MariaDB, MSSQL and SQLite are supported. If you do not have a strong preference for any of the aforementioned and no database from a previous installation at hand, I would recommend SQLite for smaller and PostgreSQL for larger repositories. SQLite is a built-in database and does not require any installation. So if you decide for SQLite, you can skip this section. PostgreSQL, in contrast, is an open-source database management system that can be installed as an extension of linux and other OSs. Install the PostgreSQL package by executing the following command.
sudo apt install postgreSQL
Then, open a PostgreSQL terminal by
sudo -u postgres psql -d tempplate0
and create a new user which we will be using for Gitea with the following command.
CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';
Make sure to change the password to something more secure. Now, let’s create a new database for Gitea by
CREATE DATABASE giteadb OWNER gitea;
and exit the PostgreSQL terminal by typing quit or the short version \q. After this, we can move on to installing Gitea.
Install Gitea
It’s convenient to run the Gitea service under a dedicated user. Therefore, create a new user by
sudo adduser --disabled-login --gecos 'Gitea' git
where the --disabled-login option prevents people from logging into this account and --gecos allows us to set ‘Gitea’ as a name for the user.
Switch to the newly created user by
sudo su -l git -s /bin/bash
and create a new folder for the Gitea installation in it’s home directory by executing the following commands.
cd ~
mkdir gitea
cd gitea
The next step is to download the Gitea binary to the RPi. For this, go to the Gitea download page and copy the link for the actual file. The correct file is the one that matches your OS and architecture. In my case it is gitea-1.22.6-linux-arm64 since I installed the 64-bit version of the Raspberry Pi OS. If you are unsure whether you have a 32-bit or 64-bit OS, run getconf LONG_BIT or uname -m to find out.
If you found the link to the correct file, download it into the gitea folder by using wget:
wget https://dl.gitea.com/gitea/1.22.6/gitea-1.22.6-linux-arm64 -O gitea
where you, of course, might want to adopt the link. Now, let’s give execution rights to the downloaded file by
chmod +x gitea
before leaving the gitea user and switching back to the normal user by typing exit in the terminal.
Creating a Service for Gitea
It is convenient to run Gitea as a service instead of manually from the terminal. This allows us to easily restart Gitea and will also automatically launch Gitea on startup of the RPi. Furthermore, this allows us to use the terminal for other tasks since Gitea ‘blocks’ the terminal by printing status messages after it has been started.
Create a file for the Gitea service by
sudo nano /etc/systemd/system/gitea.service
and enter the following lines into the file:
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/home/git/gitea
ExecStart=/home/git/gitea/gitea web
Restart=always
Environment=USER=git
HOME=/home/git
GITEA_WORK_DIR=/home/git/gitea
[Install]
WantedBy=multi-user.target
These lines are only an excerpt of the configuration file provided in the Gitea code.
The file is saved with Ctrl+x followed by y and then enter.
Eventually, the Gitea service needs to be enabled and started by running the following commands.
sudo systemctl enable gitea.service
sudo systemctl start gitea.service
To restart the Gitea service, type
sudo systemctl restart gitea.service
while
systemctl status gitea.service
can be used to print the current status of the service.
Initial Configuration
Now that the installation of Gitea is finished, we can proceed with the configuration of the application. For this, enter the IP address of the RPi into a browser followed by:3000 since Gitea listens on this port.
For example, type:
http://192.168.0.41:3000
You should see the installation page of Gitea where you are asked to enter the database details, set the domain name and ports. Use the database settings from the PostgreSQL installation (or SQLite) from above and make sure the Domain and Application URL fields do either contain the IP address of the RPi itself or its domain name if you set up any before.
The optional fields under Admin Account Settings allow you to set up an admin account during the installation process.
If you filled all fields with the correct values, press the Install Gitea button. After you pushed the button, it will take some time to get everything ready before you end up with the home screen of Gitea. Log in and explore the various settings and functionalities. If you are familiar with GitHub, it should be pretty straight forward.
Further Configuration and Customization
The configuration of Gitea is stored in a file that is stored under /home/git/gitea/custom/conf/app.ini. The various parameters are listed and explained in the documentation.
HTTPS
One configuration step I find important is enabling HTTPS for Gitea. To do so, login as user git navigate to the custom folder within the Gitea folder (see above) and generate a self-signed certificate by
gitea cert --host [HOST]
where [HOST] is either the IP address of your RPi or it’s domain name, depending on your exact situation.
Next, navigate to the app.ini configuration file and add or adapt the following lines:
[server]
PROTOCOL = https
ROOT_URL = https://192.168.0.41:3000/
HTTP_PORT = 3000
CERT_FILE = cert.pem
KEY_FILE = key.pem
REDIRECT_OTHER_PORT = true
PORT_TO_REDIRECT = 3080
Customization
A page in the Gitea documentation that I find very helpful is the page about costumizing Gitea. Here, all the settings and steps for changing the appearance of the interface, e.g., the elements on the homepage, can be found. Further, it is also possible to add own gitignore and license files which you can choose from the respective lists when using the server. Overall, especially these Git customizations make the usage of Gitea much more convenient.