Installing Gittea

As of writing this Github is currently experiencing something of an exodus - not exactly mass yet, but and while github dying is about as likely as the year of the linux desktop. However there are some really good reasons to not want your code on github anymore.

Gittea has some decent documentation, but I wanted to give my own download experience.

This guide covers installation on linux. Ubuntu 2404.2 LTS to be sepcific, however the steps will work on most

Installation

Firstly download the files using wget:

wget -O gitea https://dl.gitea.com/gitea/1.25.4/gitea-1.25.4-linux-amd64

this will give you a directory called gitea:

alexmgullen@alexmgullen.ca:~$ dir
gitea

To verify the installation we also want to get that same file with the .asc extension.

Note: Don’t overwrite the gitea file! make sure you write to gitea.asc

wget -O gitea.asc https://dl.gitea.com/gitea/1.25.4/gitea-1.25.4-linux-amd64.asc

We then have to make sure we can execute the gitea binary.

chmod +x gitea

Verifying the installation

To verify the installation we’ll the command from the gitea documentation.

gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2

Then we’ll verify it with the gitea.asc file we just downloaded.

gpg --verify gitea.asc gitea

As stated in the documentation

Look for the text Good signature from “Teabot teabot@gitea.io” to assert a good binary, despite warnings like This key is not certified with a trusted signature!.

Creating a user

We then need to add a user for gitea:

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

and set a password for that user

sudo passwd git

Create the required directory structure:

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

We can then copy the gitea binary to a root directory:

sudo cp gitea /usr/local/bin/gitea

Installing the database

gitea needs a database to work, here we’ll be using postgres which comes installed with ubuntu, we just need to install the tools:

sudo apt install postgresql

The Postgres documentation contains more information on installing for your specific distro.

The first thing we’ll do is set update postgres’s password authentication scheme from “md5” to “scram-sha-256”. To do this we need to set the password_encryption in postgres.conf

password_encryption = scram-sha-256

If you can’t find postgres.conf you can run the command:

sudo -u postgres psql -c 'SHOW config_file';

to show you where this file is:

               config_file
-----------------------------------------
 /etc/postgresql/16/main/postgresql.conf
(1 row)

I restarted postgres, just in case:

sudo systemctl restart postgresql

Then you can then enter the postgres shell:

sudo -u postgres psql

And set your gitea password:

CREATE ROLE gitea WITH LOGIN PASSWORD '<your_password_here>';

Now we create our Gitea database:

CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';

We can then leave the posgtres shell:

\q

We then add this line to the pg_hba.conf file which will be in the same directory as posgtresql.conf the # DO NOT DISABLE line, if that exists in your config.

# Gitea permissions
local    giteadb    gitea    scram-sha-256


# DO NOT DISABLE!
# If you change this first entry you will need to make sure that the
# database superuser can access the database using some other method.
# Noninteractive access to all databases is required during automatic
# maintenance (custom daily cronjobs, replication, and similar tasks).
#
# Database administrative login by Unix domain socket
local   all             postgres                                peer
...

I’d reccomend restarting postgres after doing this:

sudo systemctl restart postgresql

Finally you can test that this connection works using

psql -U gitea -d giteadb -W

Note: If you get a FATAL: Peer authentication failed for user "gitea" you are likely encountering conflicting permissions in pg_hba.conf, unfortunately I can’t help you much with this issue as I’m not an expert in that area, but I can give you this stackoverflow thread that might help you get started. Go gettum champ.

Running as a service

For the purpose of this tutorial I’ll be running it as a systemd service.

To create a service first we create a gitea.service in /etc/systemd/system/. I use this configuration, however a much more complete example of a .service file can be found in their repo.

[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target
Wants=postgresql.service
After=postgresql.service

[Service]
# Uncomment the next line if you have repos with lots of files and get a HTTP 500 error because of that
# LimitNOFILE=524288:524288
RestartSec=2s
Type=simple
User=gitea
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
###
# In some cases, when using CapabilityBoundingSet and AmbientCapabilities option, you may want to
# set the following value to false to allow capabilities to be applied on gitea process. The following
# value if set to true sandboxes gitea service and prevent any processes from running with privileges
# in the host user namespace.
###
#PrivateUsers=false
###

[Install]
WantedBy=multi-user.target

Then run ye ole systemctl commands to enable gitea

sudo systemctl start gitea
sudo systemctl enable gitea

and check that the service is running correctly:

● gitea.service - Gitea (Git with a cup of tea)
     Loaded: loaded (/etc/systemd/system/gitea.service; enabled; preset: enabled)

finally, once everything is done we can do

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

to turn our /etc/gitea directory readonly.

Web hosting

If you are running a server with a single domain this should work fine, however if you are running behind a reverse proxy like nginx, you’ll have to pass gitea through the reverse proxy like so:

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name <server_name>

    ssl_certificate <path_to_ssl_certificate>
    ssl_certificate_key <path_to_ssl_certificate_key>

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

And with that you should have a working gitea configuration. The rest should just be the gittea oob experience. Hope you found this a bit helpful and if you have any questions please reach out to “developer” at symbol “alexmgullen.ca”.